patram 0.6.2 → 0.8.0

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-cli-arguments-helpers.js

@@ -160,6 +160,10 @@ export function buildCommandArguments(
     return ['--where', parsed_values.where];
   }
 
+  if (command_name === 'refs' && parsed_values.where !== undefined) {
+    return [command_positionals[0], '--where', parsed_values.where];
+  }
+
   return command_positionals;
 }
 
@@ -305,7 +309,7 @@ function findMissingOptionValue(option_tokens) {
   for (const token of option_tokens) {
     if (token.name === 'where' && typeof token.value !== 'string') {
       return {
-        argument_label: '<name> or --where "<clause>"',
+        argument_label: "<name> or --where '<clause>'",
         code: 'missing_required_argument',
         command_name: 'query',
       };
@@ -401,11 +405,14 @@ function validateCommandPositionals(command_name, command_positionals) {
       };
     }
 
-    if (command_name === 'show' && command_definition.missing_argument_label) {
+    if (
+      (command_name === 'refs' || command_name === 'show') &&
+      command_definition.missing_argument_label
+    ) {
       return {
         argument_label: command_definition.missing_argument_label,
         code: 'missing_required_argument',
-        command_name: 'show',
+        command_name,
       };
     }
 
@@ -422,7 +429,7 @@ function validateCommandPositionals(command_name, command_positionals) {
 
   if (command_name === 'query' && command_positionals.length === 0) {
     return {
-      argument_label: '<name> or --where "<clause>"',
+      argument_label: "<name> or --where '<clause>'",
       code: 'missing_required_argument',
       command_name: 'query',
     };

package/lib/parse-cli-arguments.types.ts

@@ -1,4 +1,10 @@
-export type CliCommandName = 'check' | 'fields' | 'query' | 'queries' | 'show';
+export type CliCommandName =
+  | 'check'
+  | 'fields'
+  | 'query'
+  | 'queries'
+  | 'refs'
+  | 'show';
 export type CliHelpTopicName = 'query-language';
 export type CliHelpTargetKind = 'root' | 'command' | 'topic';
 
@@ -34,7 +40,7 @@ export type CliParseError =
   | {
       code: 'missing_required_argument';
       argument_label: string;
-      command_name: 'query' | 'show';
+      command_name: 'query' | 'refs' | 'show';
     }
   | {
       code: 'option_not_valid_for_command';

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