patram 0.6.2 → 0.8.0

package/lib/load-patram-config.d.ts

@@ -0,0 +1,384 @@
+/**
+ * @typedef {object} LoadPatramConfigResult
+ * @property {PatramRepoConfig | null} config
+ * @property {string} config_path
+ * @property {PatramDiagnostic[]} diagnostics
+ */
+/**
+ * Load and validate the repo Patram config.
+ *
+ * @param {string} [project_directory]
+ * @returns {Promise<LoadPatramConfigResult>}
+ */
+export function loadPatramConfig(project_directory?: string): Promise<LoadPatramConfigResult>;
+export type LoadPatramConfigResult = {
+    config: PatramRepoConfig | null;
+    config_path: string;
+    diagnostics: PatramDiagnostic[];
+};
+export type PatramDiagnostic = {
+    code: string;
+    column: number;
+    level: "error";
+    line: number;
+    message: string;
+    path: string;
+};
+export type StoredQueryConfig = z.output<typeof stored_query_schema>;
+export type DerivedSummaryScalar = z.output<typeof derived_summary_scalar_schema>;
+export type DerivedSummaryCountConfig = z.output<typeof derived_summary_count_schema>;
+export type DerivedSummarySelectCaseConfig = z.output<typeof derived_summary_select_case_schema>;
+export type DerivedSummaryFieldConfig = z.output<typeof derived_summary_field_schema>;
+export type DerivedSummaryConfig = z.output<typeof derived_summary_schema>;
+export type FieldDisplayConfig = z.output<typeof field_display_schema>;
+export type FieldQueryConfig = z.output<typeof field_query_schema>;
+export type MetadataFieldConfig = z.output<typeof metadata_field_schema>;
+export type ClassFieldRuleConfig = z.output<typeof class_field_rule_schema>;
+export type ClassSchemaConfig = z.output<typeof class_schema_schema>;
+export type RepoClassConfig = z.output<typeof repo_class_definition_schema>;
+export type PathClassConfig = z.output<typeof path_class_schema>;
+export type PatramRepoConfig = z.output<typeof patram_repo_config_schema>;
+import { z } from 'zod';
+/**
+ * @typedef {object} PatramDiagnostic
+ * @property {string} code
+ * @property {number} column
+ * @property {'error'} level
+ * @property {number} line
+ * @property {string} message
+ * @property {string} path
+ */
+/**
+ * @typedef {z.output<typeof stored_query_schema>} StoredQueryConfig
+ */
+declare const stored_query_schema: z.ZodObject<{
+    where: z.ZodString;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof derived_summary_scalar_schema>} DerivedSummaryScalar
+ */
+declare const derived_summary_scalar_schema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>;
+/**
+ * @typedef {z.output<typeof derived_summary_count_schema>} DerivedSummaryCountConfig
+ */
+declare const derived_summary_count_schema: z.ZodObject<{
+    traversal: z.ZodString;
+    where: z.ZodString;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof derived_summary_select_case_schema>} DerivedSummarySelectCaseConfig
+ */
+declare const derived_summary_select_case_schema: z.ZodObject<{
+    value: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>;
+    when: z.ZodString;
+}, z.core.$strict>;
+declare const derived_summary_field_schema: z.ZodUnion<readonly [z.ZodObject<{
+    count: z.ZodObject<{
+        traversal: z.ZodString;
+        where: z.ZodString;
+    }, z.core.$strict>;
+    name: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    default: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>;
+    name: z.ZodString;
+    select: z.ZodArray<z.ZodObject<{
+        value: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>;
+        when: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>]>;
+/**
+ * @typedef {z.output<typeof derived_summary_schema>} DerivedSummaryConfig
+ */
+declare const derived_summary_schema: z.ZodObject<{
+    classes: z.ZodArray<z.ZodString>;
+    fields: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        count: z.ZodObject<{
+            traversal: z.ZodString;
+            where: z.ZodString;
+        }, z.core.$strict>;
+        name: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        default: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>;
+        name: z.ZodString;
+        select: z.ZodArray<z.ZodObject<{
+            value: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>;
+            when: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof field_display_schema>} FieldDisplayConfig
+ */
+declare const field_display_schema: z.ZodObject<{
+    hidden: z.ZodOptional<z.ZodBoolean>;
+    order: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof field_query_schema>} FieldQueryConfig
+ */
+declare const field_query_schema: z.ZodObject<{
+    contains: z.ZodOptional<z.ZodBoolean>;
+    prefix: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof metadata_field_schema>} MetadataFieldConfig
+ */
+declare const metadata_field_schema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    query: z.ZodOptional<z.ZodObject<{
+        contains: z.ZodOptional<z.ZodBoolean>;
+        prefix: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    type: z.ZodLiteral<"string">;
+    display: z.ZodOptional<z.ZodObject<{
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+    path_class: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"integer">;
+    display: z.ZodOptional<z.ZodObject<{
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+    path_class: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"enum">;
+    values: z.ZodArray<z.ZodString>;
+    display: z.ZodOptional<z.ZodObject<{
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+    path_class: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"path">;
+    display: z.ZodOptional<z.ZodObject<{
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+    path_class: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"glob">;
+    display: z.ZodOptional<z.ZodObject<{
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+    path_class: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"date">;
+    display: z.ZodOptional<z.ZodObject<{
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+    path_class: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"date_time">;
+    display: z.ZodOptional<z.ZodObject<{
+        hidden: z.ZodOptional<z.ZodBoolean>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    multiple: z.ZodOptional<z.ZodBoolean>;
+    path_class: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "type">;
+/**
+ * @typedef {z.output<typeof class_field_rule_schema>} ClassFieldRuleConfig
+ */
+declare const class_field_rule_schema: z.ZodObject<{
+    markdown_styles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    presence: z.ZodEnum<{
+        optional: "optional";
+        required: "required";
+        forbidden: "forbidden";
+    }>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof class_schema_schema>} ClassSchemaConfig
+ */
+declare const class_schema_schema: z.ZodObject<{
+    document_path_class: z.ZodOptional<z.ZodString>;
+    fields: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        markdown_styles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        presence: z.ZodEnum<{
+            optional: "optional";
+            required: "required";
+            forbidden: "forbidden";
+        }>;
+    }, z.core.$strict>>>;
+    markdown_styles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    mixed_styles: z.ZodOptional<z.ZodString>;
+    unknown_fields: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        ignore: "ignore";
+    }>>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof repo_class_definition_schema>} RepoClassConfig
+ */
+declare const repo_class_definition_schema: z.ZodObject<{
+    builtin: z.ZodOptional<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+    schema: z.ZodOptional<z.ZodObject<{
+        document_path_class: z.ZodOptional<z.ZodString>;
+        fields: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+            markdown_styles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            presence: z.ZodEnum<{
+                optional: "optional";
+                required: "required";
+                forbidden: "forbidden";
+            }>;
+        }, z.core.$strict>>>;
+        markdown_styles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        mixed_styles: z.ZodOptional<z.ZodString>;
+        unknown_fields: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            ignore: "ignore";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof path_class_schema>} PathClassConfig
+ */
+declare const path_class_schema: z.ZodObject<{
+    prefixes: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof patram_repo_config_schema>} PatramRepoConfig
+ */
+declare const patram_repo_config_schema: z.ZodObject<{
+    classes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        builtin: z.ZodOptional<z.ZodBoolean>;
+        label: z.ZodOptional<z.ZodString>;
+        schema: z.ZodOptional<z.ZodObject<{
+            document_path_class: z.ZodOptional<z.ZodString>;
+            fields: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                markdown_styles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                presence: z.ZodEnum<{
+                    optional: "optional";
+                    required: "required";
+                    forbidden: "forbidden";
+                }>;
+            }, z.core.$strict>>>;
+            markdown_styles: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            mixed_styles: z.ZodOptional<z.ZodString>;
+            unknown_fields: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                ignore: "ignore";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    derived_summaries: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        classes: z.ZodArray<z.ZodString>;
+        fields: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            count: z.ZodObject<{
+                traversal: z.ZodString;
+                where: z.ZodString;
+            }, z.core.$strict>;
+            name: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            default: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>;
+            name: z.ZodString;
+            select: z.ZodArray<z.ZodObject<{
+                value: z.ZodUnion<readonly [z.ZodBoolean, z.ZodNumber, z.ZodString, z.ZodNull]>;
+                when: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>]>>;
+    }, z.core.$strict>>>;
+    fields: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+        query: z.ZodOptional<z.ZodObject<{
+            contains: z.ZodOptional<z.ZodBoolean>;
+            prefix: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        type: z.ZodLiteral<"string">;
+        display: z.ZodOptional<z.ZodObject<{
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            order: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+        path_class: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"integer">;
+        display: z.ZodOptional<z.ZodObject<{
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            order: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+        path_class: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"enum">;
+        values: z.ZodArray<z.ZodString>;
+        display: z.ZodOptional<z.ZodObject<{
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            order: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+        path_class: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"path">;
+        display: z.ZodOptional<z.ZodObject<{
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            order: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+        path_class: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"glob">;
+        display: z.ZodOptional<z.ZodObject<{
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            order: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+        path_class: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"date">;
+        display: z.ZodOptional<z.ZodObject<{
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            order: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+        path_class: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"date_time">;
+        display: z.ZodOptional<z.ZodObject<{
+            hidden: z.ZodOptional<z.ZodBoolean>;
+            order: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        multiple: z.ZodOptional<z.ZodBoolean>;
+        path_class: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "type">>>;
+    include: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    mappings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        emit: z.ZodOptional<z.ZodObject<{
+            relation: z.ZodString;
+            target: z.ZodEnum<{
+                path: "path";
+                value: "value";
+            }>;
+            target_class: z.ZodString;
+        }, z.core.$strict>>;
+        node: z.ZodOptional<z.ZodObject<{
+            class: z.ZodString;
+            field: z.ZodString;
+            key: z.ZodOptional<z.ZodEnum<{
+                path: "path";
+                value: "value";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    path_classes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        prefixes: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    queries: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        where: z.ZodString;
+    }, z.core.$strict>>>;
+    relations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        builtin: z.ZodOptional<z.ZodBoolean>;
+        from: z.ZodArray<z.ZodString>;
+        to: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export {};

package/lib/load-patram-config.types.d.ts

@@ -0,0 +1,45 @@
+export type StoredQueryConfig = import('./load-patram-config.js').StoredQueryConfig;
+export type FieldDisplayConfig = import('./load-patram-config.js').FieldDisplayConfig;
+export type FieldQueryConfig = import('./load-patram-config.js').FieldQueryConfig;
+export type FieldValueTypeName = import('./load-patram-config.js').MetadataFieldConfig['type'];
+export type MetadataFieldConfig = import('./load-patram-config.js').MetadataFieldConfig;
+export type StringFieldConfig = Extract<MetadataFieldConfig, {
+    type: 'string';
+}>;
+export type IntegerFieldConfig = Extract<MetadataFieldConfig, {
+    type: 'integer';
+}>;
+export type EnumFieldConfig = Extract<MetadataFieldConfig, {
+    type: 'enum';
+}>;
+export type PathFieldConfig = Extract<MetadataFieldConfig, {
+    type: 'path';
+}>;
+export type GlobFieldConfig = Extract<MetadataFieldConfig, {
+    type: 'glob';
+}>;
+export type DateFieldConfig = Extract<MetadataFieldConfig, {
+    type: 'date';
+}>;
+export type DateTimeFieldConfig = Extract<MetadataFieldConfig, {
+    type: 'date_time';
+}>;
+export type ClassFieldRuleConfig = import('./load-patram-config.js').ClassFieldRuleConfig;
+export type DirectiveTypeConfig = MetadataFieldConfig;
+export type MetadataDirectiveRuleConfig = ClassFieldRuleConfig;
+export type ClassSchemaConfig = import('./load-patram-config.js').ClassSchemaConfig;
+export type MetadataSchemaConfig = ClassSchemaConfig;
+export type PathClassConfig = import('./load-patram-config.js').PathClassConfig;
+export type DerivedSummaryScalar = import('./load-patram-config.js').DerivedSummaryScalar;
+export type DerivedSummarySelectCaseConfig = import('./load-patram-config.js').DerivedSummarySelectCaseConfig;
+export type DerivedSummaryFieldConfig = import('./load-patram-config.js').DerivedSummaryFieldConfig;
+export type DerivedSummaryCountFieldConfig = Extract<DerivedSummaryFieldConfig, {
+    count: unknown;
+}>;
+export type DerivedSummarySelectFieldConfig = Extract<DerivedSummaryFieldConfig, {
+    select: unknown;
+}>;
+export type DerivedSummaryConfig = import('./load-patram-config.js').DerivedSummaryConfig;
+export type PatramRepoConfig = import('./load-patram-config.js').PatramRepoConfig;
+export type PatramDiagnostic = import('./load-patram-config.js').PatramDiagnostic;
+export type LoadPatramConfigResult = import('./load-patram-config.js').LoadPatramConfigResult;

package/lib/load-project-graph.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Project graph loading pipeline.
+ *
+ * Loads config, scans source files, parses claims, and materializes the graph
+ * used by CLI commands.
+ *
+ * Kind: graph
+ * Status: active
+ * Uses Term: ../docs/reference/terms/claim.md
+ * Uses Term: ../docs/reference/terms/graph.md
+ * Uses Term: ../docs/reference/terms/mapping.md
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/dogfood-query-graph-v0.md
+ * @patram
+ * @see {@link ./parse-claims.js}
+ * @see {@link ./build-graph.js}
+ */
+/**
+ * Load config, source files, claims, and the materialized graph for one
+ * project directory.
+ *
+ * @param {string} project_directory
+ * @returns {Promise<{ claims: PatramClaim[], config: PatramRepoConfig, diagnostics: PatramDiagnostic[], graph: BuildGraphResult, source_file_paths: string[] }>}
+ */
+export function loadProjectGraph(project_directory: string): Promise<{
+    claims: PatramClaim[];
+    config: PatramRepoConfig;
+    diagnostics: PatramDiagnostic[];
+    graph: BuildGraphResult;
+    source_file_paths: string[];
+}>;
+import type { PatramClaim } from './parse-claims.types.ts';
+import type { PatramRepoConfig } from './load-patram-config.types.ts';
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { BuildGraphResult } from './build-graph.types.ts';

package/lib/output-view.types.d.ts

@@ -0,0 +1,88 @@
+export type OutputDerivedValue = boolean | number | string | null;
+export interface OutputDerivedField {
+    name: string;
+    value: OutputDerivedValue;
+}
+export interface OutputDerivedSummary {
+    fields: OutputDerivedField[];
+    name: string;
+}
+export interface OutputMetadataField {
+    name: string;
+    value: string | string[];
+}
+export interface OutputViewSummary {
+    count: number;
+    kind: 'incoming_reference_list' | 'resolved_link_list' | 'result_list' | 'stored_query_list';
+}
+export interface QueryOutputViewSummary extends OutputViewSummary {
+    kind: 'result_list';
+    limit: number;
+    offset: number;
+    total_count: number;
+}
+export interface OutputNodeItem {
+    derived_summary?: OutputDerivedSummary;
+    fields: Record<string, string | string[]>;
+    id: string;
+    kind: 'node';
+    node_kind: string;
+    path?: string;
+    title: string;
+    visible_fields: OutputMetadataField[];
+}
+export interface OutputStoredQueryItem {
+    kind: 'stored_query';
+    name: string;
+    where: string;
+}
+export interface OutputResolvedLinkTarget {
+    derived_summary?: OutputDerivedSummary;
+    fields: Record<string, string | string[]>;
+    id: string;
+    kind: string;
+    path?: string;
+    title: string;
+    visible_fields: OutputMetadataField[];
+}
+export interface OutputResolvedLinkItem {
+    kind: 'resolved_link';
+    label: string;
+    reference: number;
+    target: OutputResolvedLinkTarget;
+}
+export interface QueryOutputView {
+    command: 'query';
+    hints: string[];
+    items: OutputNodeItem[];
+    summary: QueryOutputViewSummary;
+}
+export interface QueriesOutputView {
+    command: 'queries';
+    hints: string[];
+    items: OutputStoredQueryItem[];
+    summary: OutputViewSummary;
+}
+export interface ShowOutputView {
+    command: 'show';
+    document?: OutputNodeItem;
+    hints: string[];
+    incoming_summary: Record<string, number>;
+    items: OutputResolvedLinkItem[];
+    path: string;
+    rendered_source: string;
+    source: string;
+    summary: OutputViewSummary;
+}
+export interface RefsOutputView {
+    command: 'refs';
+    hints: string[];
+    incoming: Record<string, OutputNodeItem[]>;
+    node: OutputNodeItem;
+    summary: OutputViewSummary;
+}
+export type OutputView = QueryOutputView | QueriesOutputView | RefsOutputView | ShowOutputView;
+export interface ResolvedOutputMode {
+    color_enabled: boolean;
+    renderer_name: 'json' | 'plain' | 'rich';
+}

package/lib/output-view.types.ts

@@ -19,7 +19,11 @@ export interface OutputMetadataField {
 
 export interface OutputViewSummary {
   count: number;
-  kind: 'resolved_link_list' | 'result_list' | 'stored_query_list';
+  kind:
+    | 'incoming_reference_list'
+    | 'resolved_link_list'
+    | 'result_list'
+    | 'stored_query_list';
 }
 
 export interface QueryOutputViewSummary extends OutputViewSummary {
@@ -81,6 +85,7 @@ export interface ShowOutputView {
   command: 'show';
   document?: OutputNodeItem;
   hints: string[];
+  incoming_summary: Record<string, number>;
   items: OutputResolvedLinkItem[];
   path: string;
   rendered_source: string;
@@ -88,7 +93,19 @@ export interface ShowOutputView {
   summary: OutputViewSummary;
 }
 
-export type OutputView = QueryOutputView | QueriesOutputView | ShowOutputView;
+export interface RefsOutputView {
+  command: 'refs';
+  hints: string[];
+  incoming: Record<string, OutputNodeItem[]>;
+  node: OutputNodeItem;
+  summary: OutputViewSummary;
+}
+
+export type OutputView =
+  | QueryOutputView
+  | QueriesOutputView
+  | RefsOutputView
+  | ShowOutputView;
 
 export interface ResolvedOutputMode {
   color_enabled: boolean;

package/lib/overlay-graph.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @import { BuildGraphResult, GraphEdge, GraphNode } from './build-graph.types.ts';
+ */
+/**
+ * @typedef {{
+ *   document_node_ids?: BuildGraphResult['document_node_ids'],
+ *   edges?: GraphEdge[],
+ *   nodes?: GraphNode[] | Record<string, GraphNode>,
+ * }} GraphOverlay
+ */
+/**
+ * Graph overlay composition.
+ *
+ * Composes transient nodes and edges onto an existing Patram graph while
+ * preserving the graph shape expected by query and document resolution
+ * helpers.
+ *
+ * Kind: graph
+ * Status: active
+ * Uses Term: ../docs/reference/terms/document.md
+ * Uses Term: ../docs/reference/terms/graph.md
+ * Tracked in: ../docs/plans/v0/package-graph-overlay-helper.md
+ * Decided by: ../docs/decisions/package-graph-overlay-helper.md
+ * @patram
+ * @see {@link ./query-graph.js}
+ * @see {@link ../docs/decisions/package-graph-overlay-helper.md}
+ */
+/**
+ * Compose additional nodes and edges onto a loaded Patram graph.
+ *
+ * @param {BuildGraphResult} base_graph
+ * @param {GraphOverlay} [graph_overlay]
+ * @returns {BuildGraphResult}
+ */
+export function overlayGraph(base_graph: BuildGraphResult, graph_overlay?: GraphOverlay): BuildGraphResult;
+export type GraphOverlay = {
+    document_node_ids?: BuildGraphResult["document_node_ids"];
+    edges?: GraphEdge[];
+    nodes?: GraphNode[] | Record<string, GraphNode>;
+};
+import type { BuildGraphResult } from './build-graph.types.ts';
+import type { GraphEdge } from './build-graph.types.ts';
+import type { GraphNode } from './build-graph.types.ts';