patram 0.1.1 → 0.2.0

package/lib/derived-summary.js

@@ -0,0 +1,278 @@
+/**
+ * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
+ * @import { OutputDerivedSummary } from './output-view.types.ts';
+ * @import { DerivedSummaryConfig, DerivedSummaryFieldConfig, DerivedSummaryScalar, PatramRepoConfig } from './load-patram-config.types.ts';
+ */
+
+import { queryGraph } from './query-graph.js';
+
+/**
+ * Derived summary evaluation.
+ *
+ * Evaluates repo-configured output-only metadata for graph nodes without
+ * mutating graph state.
+ *
+ * Kind: output
+ * Status: active
+ * Tracked in: ../docs/plans/v0/declarative-derived-summaries.md
+ * Decided by: ../docs/decisions/declarative-derived-summary-config.md
+ * Decided by: ../docs/decisions/declarative-derived-summary-side-effects.md
+ * @patram
+ * @see {@link ./load-patram-config.js}
+ * @see {@link ./render-output-view.js}
+ */
+
+/**
+ * @typedef {{
+ *   evaluate: (graph_node: GraphNode) => OutputDerivedSummary | null,
+ * }} DerivedSummaryEvaluator
+ */
+
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @param {BuildGraphResult} graph
+ * @returns {DerivedSummaryEvaluator}
+ */
+export function createDerivedSummaryEvaluator(repo_config, graph) {
+  const summary_by_kind = createSummaryByKind(repo_config.derived_summaries);
+  /** @type {Map<string, Set<string>>} */
+  const matching_node_id_cache = new Map();
+
+  return {
+    evaluate(graph_node) {
+      const configured_summary = summary_by_kind.get(graph_node.kind);
+
+      if (!configured_summary) {
+        return null;
+      }
+
+      return {
+        fields: configured_summary.definition.fields.map(
+          (field_definition) => ({
+            name: field_definition.name,
+            value: evaluateFieldValue(
+              field_definition,
+              configured_summary.definition,
+              graph,
+              graph_node,
+              matching_node_id_cache,
+            ),
+          }),
+        ),
+        name: configured_summary.name,
+      };
+    },
+  };
+}
+
+/**
+ * @param {DerivedSummaryFieldConfig} field_definition
+ * @param {DerivedSummaryConfig} summary_definition
+ * @param {BuildGraphResult} graph
+ * @param {GraphNode} graph_node
+ * @param {Map<string, Set<string>>} matching_node_id_cache
+ * @returns {DerivedSummaryScalar}
+ */
+function evaluateFieldValue(
+  field_definition,
+  summary_definition,
+  graph,
+  graph_node,
+  matching_node_id_cache,
+) {
+  if ('count' in field_definition) {
+    return countMatchingTraversalNodes(
+      graph,
+      graph_node,
+      field_definition.count.traversal,
+      field_definition.count.where,
+      matching_node_id_cache,
+    );
+  }
+
+  return selectFieldValue(
+    graph,
+    graph_node,
+    summary_definition,
+    field_definition,
+    matching_node_id_cache,
+  );
+}
+
+/**
+ * @param {BuildGraphResult} graph
+ * @param {GraphNode} graph_node
+ * @param {string} traversal_text
+ * @param {string} where_clause
+ * @param {Map<string, Set<string>>} matching_node_id_cache
+ * @returns {number}
+ */
+function countMatchingTraversalNodes(
+  graph,
+  graph_node,
+  traversal_text,
+  where_clause,
+  matching_node_id_cache,
+) {
+  const target_node_ids = getTraversedNodeIds(
+    graph,
+    graph_node.id,
+    traversal_text,
+  );
+
+  if (target_node_ids.size === 0) {
+    return 0;
+  }
+
+  const matching_node_ids = getMatchingNodeIds(
+    graph,
+    where_clause,
+    matching_node_id_cache,
+  );
+  let matching_count = 0;
+
+  for (const target_node_id of target_node_ids) {
+    if (matching_node_ids.has(target_node_id)) {
+      matching_count += 1;
+    }
+  }
+
+  return matching_count;
+}
+
+/**
+ * @param {BuildGraphResult} graph
+ * @param {GraphNode} graph_node
+ * @param {DerivedSummaryConfig} summary_definition
+ * @param {Extract<DerivedSummaryFieldConfig, { select: unknown }>} field_definition
+ * @param {Map<string, Set<string>>} matching_node_id_cache
+ * @returns {DerivedSummaryScalar}
+ */
+function selectFieldValue(
+  graph,
+  graph_node,
+  summary_definition,
+  field_definition,
+  matching_node_id_cache,
+) {
+  for (const select_case of field_definition.select) {
+    const matching_node_ids = getMatchingNodeIds(
+      graph,
+      select_case.when,
+      matching_node_id_cache,
+    );
+
+    if (matching_node_ids.has(graph_node.id)) {
+      return select_case.value;
+    }
+  }
+
+  return field_definition.default;
+}
+
+/**
+ * @param {BuildGraphResult} graph
+ * @param {string} where_clause
+ * @param {Map<string, Set<string>>} matching_node_id_cache
+ * @returns {Set<string>}
+ */
+function getMatchingNodeIds(graph, where_clause, matching_node_id_cache) {
+  const cached_node_ids = matching_node_id_cache.get(where_clause);
+
+  if (cached_node_ids) {
+    return cached_node_ids;
+  }
+
+  const query_result = queryGraph(graph, where_clause);
+
+  if (query_result.diagnostics.length > 0) {
+    throw new Error(
+      `Expected derived summary query "${where_clause}" to be valid.`,
+    );
+  }
+
+  const matching_node_ids = new Set(
+    query_result.nodes.map((matching_node) => matching_node.id),
+  );
+
+  matching_node_id_cache.set(where_clause, matching_node_ids);
+
+  return matching_node_ids;
+}
+
+/**
+ * @param {BuildGraphResult} graph
+ * @param {string} node_id
+ * @param {string} traversal_text
+ * @returns {Set<string>}
+ */
+function getTraversedNodeIds(graph, node_id, traversal_text) {
+  const traversal = parseTraversal(traversal_text);
+  /** @type {Set<string>} */
+  const target_node_ids = new Set();
+
+  for (const graph_edge of graph.edges) {
+    if (graph_edge.relation !== traversal.relation_name) {
+      continue;
+    }
+
+    if (traversal.direction === 'in' && graph_edge.to === node_id) {
+      target_node_ids.add(graph_edge.from);
+    }
+
+    if (traversal.direction === 'out' && graph_edge.from === node_id) {
+      target_node_ids.add(graph_edge.to);
+    }
+  }
+
+  return target_node_ids;
+}
+
+/**
+ * @param {string} traversal_text
+ * @returns {{ direction: 'in' | 'out', relation_name: string }}
+ */
+function parseTraversal(traversal_text) {
+  const traversal_match =
+    /^(?<direction>in|out):(?<relation_name>[a-zA-Z0-9_]+)$/du.exec(
+      traversal_text,
+    );
+
+  if (
+    !traversal_match?.groups?.direction ||
+    !traversal_match.groups.relation_name
+  ) {
+    throw new Error(`Invalid derived summary traversal "${traversal_text}".`);
+  }
+
+  return {
+    direction: /** @type {'in' | 'out'} */ (traversal_match.groups.direction),
+    relation_name: traversal_match.groups.relation_name,
+  };
+}
+
+/**
+ * @param {PatramRepoConfig['derived_summaries']} derived_summaries
+ * @returns {Map<string, { definition: DerivedSummaryConfig, name: string }>}
+ */
+function createSummaryByKind(derived_summaries) {
+  /** @type {Map<string, { definition: DerivedSummaryConfig, name: string }>} */
+  const summary_by_kind = new Map();
+
+  if (!derived_summaries) {
+    return summary_by_kind;
+  }
+
+  for (const [summary_name, summary_definition] of Object.entries(
+    derived_summaries,
+  )) {
+    for (const kind_name of summary_definition.kinds) {
+      summary_by_kind.set(kind_name, {
+        definition: summary_definition,
+        name: summary_name,
+      });
+    }
+  }
+
+  return summary_by_kind;
+}

package/lib/format-derived-summary-row.js

@@ -0,0 +1,9 @@
+/**
+ * @param {import('./output-view.types.ts').OutputDerivedSummary} derived_summary
+ * @returns {string}
+ */
+export function formatDerivedSummaryRow(derived_summary) {
+  return derived_summary.fields
+    .map((field) => `${field.name}: ${String(field.value)}`)
+    .join('  ');
+}

package/lib/format-node-header.js

@@ -0,0 +1,19 @@
+/**
+ * @param {import('./output-view.types.ts').OutputNodeItem} output_item
+ * @returns {string}
+ */
+export function formatNodeHeader(output_item) {
+  if (isDocumentNode(output_item)) {
+    return `document ${output_item.path}`;
+  }
+
+  return `${output_item.node_kind} ${output_item.id}`;
+}
+
+/**
+ * @param {import('./output-view.types.ts').OutputNodeItem} output_item
+ * @returns {boolean}
+ */
+export function isDocumentNode(output_item) {
+  return output_item.id === `doc:${output_item.path}`;
+}

package/lib/format-output-item-block.js

@@ -0,0 +1,22 @@
+/**
+ * @param {{ header: string, metadata_rows: string[], metadata_indent?: string, title: string, title_indent?: string }} options
+ * @returns {string}
+ */
+export function formatOutputItemBlock(options) {
+  const metadata_indent = options.metadata_indent ?? '';
+  const title_indent = options.title_indent ?? '    ';
+  /** @type {string[]} */
+  const lines = [options.header];
+
+  if (options.metadata_rows.length > 0) {
+    lines.push(
+      ...options.metadata_rows.map(
+        (metadata_row) => `${metadata_indent}${metadata_row}`,
+      ),
+    );
+  }
+
+  lines.push('', `${title_indent}${options.title}`);
+
+  return lines.join('\n');
+}

package/lib/format-output-metadata.js

@@ -0,0 +1,62 @@
+import { formatDerivedSummaryRow } from './format-derived-summary-row.js';
+import { isDocumentNode } from './format-node-header.js';
+
+/**
+ * @param {import('./output-view.types.ts').OutputNodeItem} output_item
+ * @returns {string[]}
+ */
+export function formatOutputNodeMetadataRows(output_item) {
+  /** @type {string[]} */
+  const metadata_rows = [];
+  /** @type {string[]} */
+  const stored_metadata_fields = [];
+
+  if (isDocumentNode(output_item)) {
+    stored_metadata_fields.push(`kind: ${output_item.node_kind}`);
+  } else {
+    stored_metadata_fields.push(`path: ${output_item.path}`);
+  }
+
+  if (output_item.status) {
+    stored_metadata_fields.push(`status: ${output_item.status}`);
+  }
+
+  if (stored_metadata_fields.length > 0) {
+    metadata_rows.push(stored_metadata_fields.join('  '));
+  }
+
+  if (output_item.derived_summary) {
+    metadata_rows.push(formatDerivedSummaryRow(output_item.derived_summary));
+  }
+
+  return metadata_rows;
+}
+
+/**
+ * @param {import('./output-view.types.ts').OutputResolvedLinkTarget} target
+ * @returns {string[]}
+ */
+export function formatResolvedLinkMetadataRows(target) {
+  /** @type {string[]} */
+  const metadata_rows = [];
+  /** @type {string[]} */
+  const stored_metadata_fields = [];
+
+  if (target.kind) {
+    stored_metadata_fields.push(`kind: ${target.kind}`);
+  }
+
+  if (target.status) {
+    stored_metadata_fields.push(`status: ${target.status}`);
+  }
+
+  if (stored_metadata_fields.length > 0) {
+    metadata_rows.push(stored_metadata_fields.join('  '));
+  }
+
+  if (target.derived_summary) {
+    metadata_rows.push(formatDerivedSummaryRow(target.derived_summary));
+  }
+
+  return metadata_rows;
+}

package/lib/layout-stored-queries.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 /**
  * @import { OutputStoredQueryItem } from './output-view.types.ts';
  */
@@ -97,7 +98,22 @@ function createStoredQueryPhrases(where_clause) {
 }
 
 /**
- * @param {{ is_negated: boolean, term: { kind: 'field', field_name: 'id' | 'kind' | 'path' | 'status' | 'title', operator: '=' | '^=' | '~', value: string } | { kind: 'relation', relation_name: string } | { kind: 'relation_target', relation_name: string, target_id: string } }} clause
+ * @param {{
+ *   is_negated: boolean,
+ *   term:
+ *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }
+ *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }
+ *     | { kind: 'relation', relation_name: string }
+ *     | { kind: 'relation_target', relation_name: string, target_id: string }
+ *     | {
+ *         aggregate_name: 'any' | 'count' | 'none',
+ *         clauses: unknown[],
+ *         comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
+ *         kind: 'aggregate',
+ *         traversal: { direction: 'in' | 'out', relation_name: string },
+ *         value?: number,
+ *       },
+ * }} clause
  * @param {boolean} should_prefix_and
  * @returns {StoredQuerySegment[]}
  */
@@ -121,10 +137,27 @@ function createClausePhrase(clause, should_prefix_and) {
 }
 
 /**
- * @param {{ kind: 'field', field_name: 'id' | 'kind' | 'path' | 'status' | 'title', operator: '=' | '^=' | '~', value: string } | { kind: 'relation', relation_name: string } | { kind: 'relation_target', relation_name: string, target_id: string }} term
+ * @param {
+ *   | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }
+ *   | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }
+ *   | { kind: 'relation', relation_name: string }
+ *   | { kind: 'relation_target', relation_name: string, target_id: string }
+ *   | {
+ *       aggregate_name: 'any' | 'count' | 'none',
+ *       clauses: { is_negated: boolean, term: unknown }[],
+ *       comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
+ *       kind: 'aggregate',
+ *       traversal: { direction: 'in' | 'out', relation_name: string },
+ *       value?: number,
+ *     }
+ * } term
  * @returns {StoredQuerySegment[]}
  */
 function createTermSegments(term) {
+  if (term.kind === 'aggregate') {
+    return createAggregateSegments(term);
+  }
+
   if (term.kind === 'field') {
     return [
       { kind: 'field_name', text: term.field_name },
@@ -133,6 +166,10 @@ function createTermSegments(term) {
     ];
   }
 
+  if (term.kind === 'field_set') {
+    return createFieldSetSegments(term);
+  }
+
   if (term.kind === 'relation_target') {
     return [
       { kind: 'field_name', text: term.relation_name },
@@ -147,6 +184,117 @@ function createTermSegments(term) {
   ];
 }
 
+/**
+ * @param {{ field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }} term
+ * @returns {StoredQuerySegment[]}
+ */
+function createFieldSetSegments(term) {
+  return [
+    { kind: 'field_name', text: term.field_name },
+    { kind: 'plain', text: ' ' },
+    { kind: 'operator', text: term.operator },
+    { kind: 'plain', text: ' ' },
+    { kind: 'operator', text: '[' },
+    ...createListSegments(term.values),
+    { kind: 'operator', text: ']' },
+  ];
+}
+
+/**
+ * @param {{
+ *   aggregate_name: 'any' | 'count' | 'none',
+ *   clauses: { is_negated: boolean, term: unknown }[],
+ *   comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
+ *   kind: 'aggregate',
+ *   traversal: { direction: 'in' | 'out', relation_name: string },
+ *   value?: number,
+ * }} term
+ * @returns {StoredQuerySegment[]}
+ */
+function createAggregateSegments(term) {
+  /** @type {StoredQuerySegment[]} */
+  const segments = [
+    { kind: 'field_name', text: term.aggregate_name },
+    { kind: 'operator', text: '(' },
+    ...createTraversalSegments(term.traversal),
+    { kind: 'operator', text: ', ' },
+    ...createNestedClauseSegments(term.clauses),
+    { kind: 'operator', text: ')' },
+  ];
+
+  if (term.aggregate_name === 'count') {
+    segments.push({ kind: 'plain', text: ' ' });
+    segments.push({ kind: 'operator', text: term.comparison ?? '=' });
+    segments.push({ kind: 'plain', text: ' ' });
+    segments.push({ kind: 'literal', text: String(term.value ?? 0) });
+  }
+
+  return segments;
+}
+
+/**
+ * @param {{ direction: 'in' | 'out', relation_name: string }} traversal
+ * @returns {StoredQuerySegment[]}
+ */
+function createTraversalSegments(traversal) {
+  return [
+    { kind: 'field_name', text: traversal.direction },
+    { kind: 'operator', text: ':' },
+    { kind: 'field_name', text: traversal.relation_name },
+  ];
+}
+
+/**
+ * @param {{ is_negated: boolean, term: unknown }[]} clauses
+ * @returns {StoredQuerySegment[]}
+ */
+function createNestedClauseSegments(clauses) {
+  return clauses.flatMap((clause, clause_index) => {
+    const clause_phrase = createClausePhrase(
+      /** @type {{
+       *   is_negated: boolean,
+       *   term:
+       *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }
+       *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }
+       *     | { kind: 'relation', relation_name: string }
+       *     | { kind: 'relation_target', relation_name: string, target_id: string }
+       *     | {
+       *         aggregate_name: 'any' | 'count' | 'none',
+       *         clauses: { is_negated: boolean, term: unknown }[],
+       *         comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
+       *         kind: 'aggregate',
+       *         traversal: { direction: 'in' | 'out', relation_name: string },
+       *         value?: number,
+       *       },
+       * }} */ (clause),
+      clause_index > 0,
+    );
+
+    if (clause_index === 0) {
+      return clause_phrase;
+    }
+
+    return [{ kind: 'plain', text: ' ' }, ...clause_phrase];
+  });
+}
+
+/**
+ * @param {string[]} values
+ * @returns {StoredQuerySegment[]}
+ */
+function createListSegments(values) {
+  return values.flatMap((value, value_index) => {
+    if (value_index === 0) {
+      return [{ kind: 'literal', text: value }];
+    }
+
+    return [
+      { kind: 'operator', text: ', ' },
+      { kind: 'literal', text: value },
+    ];
+  });
+}
+
 /**
  * @param {string} where_clause
  * @returns {StoredQuerySegment[][]}