patram 0.1.1 → 0.3.0

package/lib/derived-summary.js

@@ -0,0 +1,280 @@
+/**
+ * @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_class = createSummaryByClass(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_class.get(
+        graph_node.$class ?? 'document',
+      );
+
+      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 createSummaryByClass(derived_summaries) {
+  /** @type {Map<string, { definition: DerivedSummaryConfig, name: string }>} */
+  const summary_by_class = new Map();
+
+  if (!derived_summaries) {
+    return summary_by_class;
+  }
+
+  for (const [summary_name, summary_definition] of Object.entries(
+    derived_summaries,
+  )) {
+    for (const class_name of summary_definition.classes) {
+      summary_by_class.set(class_name, {
+        definition: summary_definition,
+        name: summary_name,
+      });
+    }
+  }
+
+  return summary_by_class;
+}

package/lib/directive-diagnostics.js

@@ -0,0 +1,38 @@
+/**
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramClaim } from './parse-claims.types.ts';
+ */
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} code
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */
+export function createOriginDiagnostic(claim, code, message) {
+  return {
+    code,
+    column: claim.origin.column,
+    level: 'error',
+    line: claim.origin.line,
+    message,
+    path: claim.origin.path,
+  };
+}
+
+/**
+ * @param {string} document_path
+ * @param {string} code
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */
+export function createDocumentDiagnostic(document_path, code, message) {
+  return {
+    code,
+    column: 1,
+    level: 'error',
+    line: 1,
+    message,
+    path: document_path,
+  };
+}

package/lib/directive-type-rules.js

@@ -0,0 +1,133 @@
+/**
+ * @import { MetadataFieldConfig } from './load-patram-config.types.ts';
+ */
+
+import { isPathLikeTarget } from './claim-helpers.js';
+
+/**
+ * @param {MetadataFieldConfig} type_definition
+ * @param {string} directive_value
+ * @returns {boolean}
+ */
+export function isDirectiveValueValid(type_definition, directive_value) {
+  if (directive_value.length === 0) {
+    return false;
+  }
+
+  switch (type_definition.type) {
+    case 'string':
+      return true;
+    case 'integer':
+      return /^-?\d+$/du.test(directive_value);
+    case 'path':
+      return isPathLikeTarget(directive_value);
+    case 'glob':
+      return true;
+    case 'date':
+      return isValidDateValue(directive_value);
+    case 'date_time':
+      return isValidDateTimeValue(directive_value);
+    default:
+      throw new Error(`Unsupported directive type "${type_definition.type}".`);
+  }
+}
+
+/**
+ * @param {string} directive_name
+ * @param {Exclude<MetadataFieldConfig['type'], 'enum'>} type_name
+ * @returns {string}
+ */
+export function getInvalidTypeMessage(directive_name, type_name) {
+  switch (type_name) {
+    case 'string':
+      return `Directive "${directive_name}" must be a non-empty string.`;
+    case 'integer':
+      return `Directive "${directive_name}" must be a base-10 integer.`;
+    case 'path':
+      return `Directive "${directive_name}" must be a path-like string.`;
+    case 'glob':
+      return `Directive "${directive_name}" must be a non-empty glob string.`;
+    case 'date':
+      return `Directive "${directive_name}" must use YYYY-MM-DD.`;
+    case 'date_time':
+      return `Directive "${directive_name}" must use YYYY-MM-DD HH:MM.`;
+    default:
+      throw new Error(`Unsupported directive type "${type_name}".`);
+  }
+}
+
+/**
+ * @param {string[]} values
+ * @returns {string}
+ */
+export function formatQuotedList(values) {
+  return values.map((value) => `"${value}"`).join(', ');
+}
+
+/**
+ * @param {string} directive_value
+ * @returns {boolean}
+ */
+function isValidDateValue(directive_value) {
+  const date_match = /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})$/du.exec(
+    directive_value,
+  );
+
+  if (!date_match?.groups) {
+    return false;
+  }
+
+  return isRealCalendarDate(
+    Number(date_match.groups.year),
+    Number(date_match.groups.month),
+    Number(date_match.groups.day),
+  );
+}
+
+/**
+ * @param {string} directive_value
+ * @returns {boolean}
+ */
+function isValidDateTimeValue(directive_value) {
+  const date_time_match =
+    /^(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2}) (?<hour>\d{2}):(?<minute>\d{2})$/du.exec(
+      directive_value,
+    );
+
+  if (!date_time_match?.groups) {
+    return false;
+  }
+
+  const hour = Number(date_time_match.groups.hour);
+  const minute = Number(date_time_match.groups.minute);
+
+  if (hour > 23 || minute > 59) {
+    return false;
+  }
+
+  return isRealCalendarDate(
+    Number(date_time_match.groups.year),
+    Number(date_time_match.groups.month),
+    Number(date_time_match.groups.day),
+  );
+}
+
+/**
+ * @param {number} year
+ * @param {number} month
+ * @param {number} day
+ * @returns {boolean}
+ */
+function isRealCalendarDate(year, month, day) {
+  if (month < 1 || month > 12 || day < 1 || day > 31) {
+    return false;
+  }
+
+  const candidate_date = new Date(Date.UTC(year, month - 1, day));
+
+  return (
+    candidate_date.getUTCFullYear() === year &&
+    candidate_date.getUTCMonth() === month - 1 &&
+    candidate_date.getUTCDate() === day
+  );
+}