patram 0.6.0 → 0.7.0

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

@@ -0,0 +1,80 @@
+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: '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[];
+    items: OutputResolvedLinkItem[];
+    path: string;
+    rendered_source: string;
+    source: string;
+    summary: OutputViewSummary;
+}
+export type OutputView = QueryOutputView | QueriesOutputView | ShowOutputView;
+export interface ResolvedOutputMode {
+    color_enabled: boolean;
+    renderer_name: 'json' | 'plain' | 'rich';
+}

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';

package/lib/overlay-graph.js

@@ -0,0 +1,191 @@
+/**
+ * @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, graph_overlay = {}) {
+  const graph_nodes = cloneGraphNodes(base_graph.nodes);
+  const overlay_nodes = normalizeOverlayNodes(graph_overlay.nodes);
+
+  applyOverlayNodes(graph_nodes, overlay_nodes);
+
+  const graph = {
+    edges: [...base_graph.edges, ...(graph_overlay.edges ?? [])],
+    nodes: graph_nodes,
+  };
+  const document_node_ids = createDocumentNodeIds(
+    base_graph.document_node_ids,
+    graph_nodes,
+    graph_overlay.document_node_ids,
+  );
+
+  attachDocumentNodeAliases(graph.nodes, document_node_ids);
+  Object.defineProperty(graph, 'document_node_ids', {
+    configurable: false,
+    enumerable: false,
+    value: document_node_ids,
+    writable: false,
+  });
+
+  return graph;
+}
+
+/**
+ * @param {BuildGraphResult['nodes']} base_graph_nodes
+ * @returns {BuildGraphResult['nodes']}
+ */
+function cloneGraphNodes(base_graph_nodes) {
+  return Object.fromEntries(
+    Object.entries(base_graph_nodes).map(([node_id, graph_node]) => [
+      node_id,
+      { ...graph_node },
+    ]),
+  );
+}
+
+/**
+ * @param {GraphOverlay['nodes']} overlay_nodes
+ * @returns {GraphNode[]}
+ */
+function normalizeOverlayNodes(overlay_nodes) {
+  if (!overlay_nodes) {
+    return [];
+  }
+
+  if (Array.isArray(overlay_nodes)) {
+    return overlay_nodes.map((graph_node) =>
+      normalizeOverlayNode(undefined, graph_node),
+    );
+  }
+
+  return Object.entries(overlay_nodes).map(([node_id, graph_node]) =>
+    normalizeOverlayNode(node_id, graph_node),
+  );
+}
+
+/**
+ * @param {string | undefined} node_id
+ * @param {GraphNode} graph_node
+ * @returns {GraphNode}
+ */
+function normalizeOverlayNode(node_id, graph_node) {
+  if (node_id === undefined) {
+    if (typeof graph_node.id !== 'string' || graph_node.id.length === 0) {
+      throw new Error('Overlay nodes must define an id.');
+    }
+
+    return { ...graph_node };
+  }
+
+  if (graph_node.id !== undefined && graph_node.id !== node_id) {
+    throw new Error(
+      `Overlay node "${node_id}" does not match embedded id "${graph_node.id}".`,
+    );
+  }
+
+  return {
+    ...graph_node,
+    id: node_id,
+  };
+}
+
+/**
+ * @param {BuildGraphResult['nodes']} graph_nodes
+ * @param {GraphNode[]} overlay_nodes
+ */
+function applyOverlayNodes(graph_nodes, overlay_nodes) {
+  for (const overlay_node of overlay_nodes) {
+    const existing_node = graph_nodes[overlay_node.id];
+
+    graph_nodes[overlay_node.id] = existing_node
+      ? { ...existing_node, ...overlay_node }
+      : { ...overlay_node };
+  }
+}
+
+/**
+ * @param {BuildGraphResult['document_node_ids']} base_document_node_ids
+ * @param {BuildGraphResult['nodes']} graph_nodes
+ * @param {BuildGraphResult['document_node_ids']} overlay_document_node_ids
+ * @returns {Record<string, string>}
+ */
+function createDocumentNodeIds(
+  base_document_node_ids,
+  graph_nodes,
+  overlay_document_node_ids,
+) {
+  /** @type {Record<string, string>} */
+  const document_node_ids = {
+    ...(base_document_node_ids ?? {}),
+  };
+
+  for (const graph_node of Object.values(graph_nodes)) {
+    if (!graph_node.$path) {
+      continue;
+    }
+
+    document_node_ids[graph_node.$path] = graph_node.id;
+  }
+
+  return {
+    ...document_node_ids,
+    ...(overlay_document_node_ids ?? {}),
+  };
+}
+
+/**
+ * @param {BuildGraphResult['nodes']} graph_nodes
+ * @param {Record<string, string>} document_node_ids
+ */
+function attachDocumentNodeAliases(graph_nodes, document_node_ids) {
+  for (const [document_path, node_id] of Object.entries(document_node_ids)) {
+    if (`doc:${document_path}` === node_id) {
+      continue;
+    }
+
+    const graph_node = graph_nodes[node_id];
+
+    if (!graph_node) {
+      continue;
+    }
+
+    Object.defineProperty(graph_nodes, `doc:${document_path}`, {
+      configurable: false,
+      enumerable: false,
+      value: graph_node,
+      writable: false,
+    });
+  }
+}

package/lib/parse-claims.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Parse one source file into claims and diagnostics.
+ *
+ * @param {ParseClaimsInput} parse_input
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
+ * @returns {ParseSourceFileResult}
+ */
+export function parseSourceFile(parse_input: ParseClaimsInput, parse_options?: {
+    multi_value_directive_names?: ReadonlySet<string>;
+}): ParseSourceFileResult;
+/**
+ * Parse a file into neutral Patram claims.
+ *
+ * @param {ParseClaimsInput} parse_input
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
+ * @returns {PatramClaim[]}
+ */
+export function parseClaims(parse_input: ParseClaimsInput, parse_options?: {
+    multi_value_directive_names?: ReadonlySet<string>;
+}): PatramClaim[];
+/**
+ * Build parser options from repo config.
+ *
+ * @param {{ fields?: Record<string, { multiple?: boolean }>, mappings?: Record<string, { emit?: unknown, node?: unknown }> } | undefined} repo_config
+ * @returns {{ multi_value_directive_names: Set<string> }}
+ */
+export function createParseOptions(repo_config: {
+    fields?: Record<string, {
+        multiple?: boolean;
+    }>;
+    mappings?: Record<string, {
+        emit?: unknown;
+        node?: unknown;
+    }>;
+} | undefined): {
+    multi_value_directive_names: Set<string>;
+};
+import type { ParseClaimsInput } from './parse-claims.types.ts';
+import type { ParseSourceFileResult } from './parse-claims.types.ts';
+import type { PatramClaim } from './parse-claims.types.ts';

package/lib/parse-claims.types.d.ts

@@ -0,0 +1,31 @@
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+export type MarkdownDirectiveStyle = 'front_matter' | 'visible_line' | 'list_item' | 'hidden_tag';
+export interface ParseClaimsInput {
+    path: string;
+    source: string;
+}
+export interface ClaimOrigin {
+    path: string;
+    line: number;
+    column: number;
+}
+export interface PatramClaim {
+    document_id: string;
+    id: string;
+    markdown_style?: MarkdownDirectiveStyle;
+    name?: string;
+    origin: ClaimOrigin;
+    parser?: string;
+    type: string;
+    value: string | {
+        target: string;
+        text: string;
+    };
+}
+export type PatramClaimFields = Omit<PatramClaim, 'document_id' | 'id' | 'origin' | 'type'> & {
+    origin?: ClaimOrigin;
+};
+export interface ParseSourceFileResult {
+    claims: PatramClaim[];
+    diagnostics: PatramDiagnostic[];
+}

package/lib/parse-jsdoc-blocks.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Collect JSDoc blocks and their activated `@patram` markers.
+ *
+ * @param {string} source_text
+ * @returns {Array<{ activation_column: number | null, activation_line: number | null, lines: Array<{ column: number, content: string, line: number }> }>}
+ */
+export function collectJsdocBlocks(source_text: string): Array<{
+    activation_column: number | null;
+    activation_line: number | null;
+    lines: Array<{
+        column: number;
+        content: string;
+        line: number;
+    }>;
+}>;

package/lib/parse-jsdoc-claims.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse JSDoc metadata claims from one source file.
+ *
+ * @param {ParseClaimsInput} parse_input
+ * @returns {ParseSourceFileResult}
+ */
+export function parseJsdocClaims(parse_input: ParseClaimsInput): ParseSourceFileResult;
+import type { ParseClaimsInput } from './parse-claims.types.ts';
+import type { ParseSourceFileResult } from './parse-claims.types.ts';

package/lib/parse-jsdoc-prose.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @param {Array<Array<{ column: number, content: string, line: number }>>} prose_paragraphs
+ * @param {Array<{ column: number, content: string, line: number }>} paragraph_lines
+ */
+export function pushJsdocParagraph(prose_paragraphs: Array<Array<{
+    column: number;
+    content: string;
+    line: number;
+}>>, paragraph_lines: Array<{
+    column: number;
+    content: string;
+    line: number;
+}>): void;
+/**
+ * @param {string} file_path
+ * @param {Array<Array<{ column: number, content: string, line: number }>>} prose_paragraphs
+ * @returns {Array<{ claim_fields: PatramClaimFields, claim_type: string, order: number }>}
+ */
+export function createJsdocProseClaimEntries(file_path: string, prose_paragraphs: Array<Array<{
+    column: number;
+    content: string;
+    line: number;
+}>>): Array<{
+    claim_fields: PatramClaimFields;
+    claim_type: string;
+    order: number;
+}>;
+import type { PatramClaimFields } from './parse-claims.types.ts';

package/lib/parse-markdown-claims.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @param {ParseClaimsInput} parse_input
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
+ * @returns {{ claims: PatramClaim[], diagnostics: PatramDiagnostic[] }}
+ */
+export function parseMarkdownClaims(parse_input: ParseClaimsInput, parse_options?: {
+    multi_value_directive_names?: ReadonlySet<string>;
+}): {
+    claims: PatramClaim[];
+    diagnostics: PatramDiagnostic[];
+};
+import type { ParseClaimsInput } from './parse-claims.types.ts';
+import type { PatramClaim } from './parse-claims.types.ts';
+import type { PatramDiagnostic } from './load-patram-config.types.ts';

package/lib/parse-markdown-directives.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @param {string} file_path
+ * @param {string[]} lines
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
+ * @returns {{ body_start: number, diagnostics: PatramDiagnostic[], directive_fields: PatramClaimFields[] }}
+ */
+export function parseFrontMatterDirectiveFields(file_path: string, lines: string[], parse_options?: {
+    multi_value_directive_names?: ReadonlySet<string>;
+}): {
+    body_start: number;
+    diagnostics: PatramDiagnostic[];
+    directive_fields: PatramClaimFields[];
+};
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {PatramClaimFields | null}
+ */
+export function matchVisibleDirectiveFields(file_path: string, line: string, line_number: number): PatramClaimFields | null;
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {PatramClaimFields | null}
+ */
+export function matchHiddenDirectiveFields(file_path: string, line: string, line_number: number): PatramClaimFields | null;
+/**
+ * @param {string} directive_label
+ * @returns {string}
+ */
+export function normalizeDirectiveName(directive_label: string): string;
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { PatramClaimFields } from './parse-claims.types.ts';

package/lib/parse-where-clause.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import {
+ *   ParseWhereClauseResult,
+ *   ParsedAggregateComparison,
+ *   ParsedAggregateName,
+ *   ParsedAggregateTerm,
+ *   ParsedExpression,
+ *   ParsedFieldName,
+ *   ParsedTerm,
+ *   ParsedTraversalTerm,
+ * } from './parse-where-clause.types.ts';
+ */
+/**
+ * @typedef {{ bindings: Record<string, string>, index: number, where_clause: string }} ParserState
+ */
+/**
+ * @typedef {{
+ *   diagnostic: PatramDiagnostic,
+ *   success: false,
+ * }} ParseFailureResult
+ */
+/**
+ * @typedef {{
+ *   expression: ParsedExpression,
+ *   success: true,
+ * } | ParseFailureResult} ParseExpressionResult
+ */
+/**
+ * @typedef {{
+ *   success: true,
+ *   term: ParsedTerm,
+ * } | ParseFailureResult} ParseTermResult
+ */
+/**
+ * @typedef {{
+ *   success: true,
+ *   value: string,
+ * } | ParseFailureResult} ParseValueResult
+ */
+/**
+ * Parse one where clause into a structured boolean expression.
+ *
+ * @param {string} where_clause
+ * @param {{ bindings?: Record<string, string> }=} options
+ * @returns {ParseWhereClauseResult}
+ */
+export function parseWhereClause(where_clause: string, options?: {
+    bindings?: Record<string, string>;
+} | undefined): ParseWhereClauseResult;
+export type ParserState = {
+    bindings: Record<string, string>;
+    index: number;
+    where_clause: string;
+};
+export type ParseFailureResult = {
+    diagnostic: PatramDiagnostic;
+    success: false;
+};
+export type ParseExpressionResult = {
+    expression: ParsedExpression;
+    success: true;
+} | ParseFailureResult;
+export type ParseTermResult = {
+    success: true;
+    term: ParsedTerm;
+} | ParseFailureResult;
+export type ParseValueResult = {
+    success: true;
+    value: string;
+} | ParseFailureResult;
+import type { ParseWhereClauseResult } from './parse-where-clause.types.ts';
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { ParsedExpression } from './parse-where-clause.types.ts';
+import type { ParsedTerm } from './parse-where-clause.types.ts';