patram 0.1.1 → 0.2.0

package/lib/load-patram-config.js

@@ -10,6 +10,8 @@ import process from 'node:process';
 import { z } from 'zod';
 
 import { parsePatramConfig } from './patram-config.js';
+import { parseWhereClause } from './parse-where-clause.js';
+import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
 import { DEFAULT_INCLUDE_PATTERNS } from './source-file-defaults.js';
 
 /**
@@ -36,8 +38,63 @@ const stored_query_schema = z
   })
   .strict();
 
+const derived_summary_scalar_schema = z.union([
+  z.boolean(),
+  z.number(),
+  z.string(),
+  z.null(),
+]);
+
+const derived_summary_count_schema = z
+  .object({
+    traversal: z
+      .string()
+      .min(1, 'Derived summary count "traversal" must not be empty.'),
+    where: z
+      .string()
+      .min(1, 'Derived summary count "where" must not be empty.'),
+  })
+  .strict();
+
+const derived_summary_select_case_schema = z
+  .object({
+    value: derived_summary_scalar_schema,
+    when: z.string().min(1, 'Derived summary select "when" must not be empty.'),
+  })
+  .strict();
+
+const derived_summary_field_schema = z
+  .object({
+    count: derived_summary_count_schema.optional(),
+    default: derived_summary_scalar_schema.optional(),
+    name: z
+      .string()
+      .regex(
+        /^[a-z][a-z0-9_]*$/du,
+        'Derived summary field names must use lower_snake_case.',
+      ),
+    select: z.array(derived_summary_select_case_schema).optional(),
+  })
+  .strict()
+  .superRefine(validateDerivedSummaryFieldDefinition);
+
+const derived_summary_schema = z
+  .object({
+    fields: z
+      .array(derived_summary_field_schema)
+      .min(1, 'Derived summary "fields" must contain at least one field.'),
+    kinds: z
+      .array(z.string().min(1))
+      .min(1, 'Derived summary "kinds" must contain at least one kind.'),
+  })
+  .strict()
+  .superRefine(validateDerivedSummaryDefinition);
+
 const patram_repo_config_schema = z
   .object({
+    derived_summaries: z
+      .record(z.string().min(1), derived_summary_schema)
+      .optional(),
     include: z
       .array(z.string().min(1, 'Include globs must not be empty.'))
       .min(1, 'Include must contain at least one glob.')
@@ -84,7 +141,15 @@ export async function loadPatramConfig(project_directory = process.cwd()) {
     return createLoadResult(null, graph_schema_diagnostics);
   }
 
-  return createLoadResult(normalizeRepoConfig(config_result.data), []);
+  const normalized_config = normalizeRepoConfig(config_result.data);
+  const derived_summary_diagnostics =
+    validateDerivedSummaries(normalized_config);
+
+  if (derived_summary_diagnostics.length > 0) {
+    return createLoadResult(null, derived_summary_diagnostics);
+  }
+
+  return createLoadResult(normalized_config, []);
 }
 
 /**
@@ -184,6 +249,88 @@ function createValidationDiagnostic(issue) {
   };
 }
 
+/**
+ * @param {{ count?: unknown, default?: unknown, select?: unknown }} field_definition
+ * @param {import('zod').RefinementCtx} refinement_context
+ */
+function validateDerivedSummaryFieldDefinition(
+  field_definition,
+  refinement_context,
+) {
+  const evaluator_count =
+    Number(field_definition.count !== undefined) +
+    Number(field_definition.select !== undefined);
+
+  if (evaluator_count !== 1) {
+    refinement_context.addIssue({
+      code: 'custom',
+      message:
+        'Derived summary fields must define exactly one of "count" or "select".',
+    });
+  }
+
+  if (
+    field_definition.count !== undefined &&
+    field_definition.default !== undefined
+  ) {
+    refinement_context.addIssue({
+      code: 'custom',
+      message: 'Derived summary count fields must not define "default".',
+      path: ['default'],
+    });
+  }
+
+  if (field_definition.select === undefined) {
+    return;
+  }
+
+  if (
+    Array.isArray(field_definition.select) &&
+    field_definition.select.length === 0
+  ) {
+    refinement_context.addIssue({
+      code: 'custom',
+      message: 'Derived summary "select" must contain at least one case.',
+      path: ['select'],
+    });
+  }
+
+  if (field_definition.default === undefined) {
+    refinement_context.addIssue({
+      code: 'custom',
+      message: 'Derived summary select fields must define "default".',
+      path: ['default'],
+    });
+  }
+}
+
+/**
+ * @param {{ fields: Array<{ name: string }> }} summary_definition
+ * @param {import('zod').RefinementCtx} refinement_context
+ */
+function validateDerivedSummaryDefinition(
+  summary_definition,
+  refinement_context,
+) {
+  const seen_field_names = new Set();
+
+  for (const [
+    field_index,
+    field_definition,
+  ] of summary_definition.fields.entries()) {
+    if (!seen_field_names.has(field_definition.name)) {
+      seen_field_names.add(field_definition.name);
+      continue;
+    }
+
+    refinement_context.addIssue({
+      code: 'custom',
+      message: `Duplicate derived summary field "${field_definition.name}".`,
+      path: ['fields', field_index, 'name'],
+    });
+  }
+}
+
 /**
  * @param {{ include: string[], queries: Record<string, { where: string }>, kinds?: unknown, mappings?: unknown, relations?: unknown }} repo_config
  * @returns {PatramDiagnostic[]}
@@ -214,6 +361,41 @@ function validateGraphSchema(repo_config) {
   return [];
 }
 
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {PatramDiagnostic[]}
+ */
+function validateDerivedSummaries(repo_config) {
+  if (!repo_config.derived_summaries) {
+    return [];
+  }
+
+  const graph_config = resolvePatramGraphConfig(repo_config);
+  const known_relation_names = new Set(Object.keys(graph_config.relations));
+  /** @type {PatramDiagnostic[]} */
+  const diagnostics = [];
+  const kind_coverage = new Map();
+
+  for (const [summary_name, summary_definition] of Object.entries(
+    repo_config.derived_summaries,
+  )) {
+    collectDuplicateKindDiagnostics(
+      diagnostics,
+      kind_coverage,
+      summary_definition.kinds,
+      summary_name,
+    );
+    collectDerivedSummaryFieldDiagnostics(
+      diagnostics,
+      known_relation_names,
+      summary_name,
+      summary_definition.fields,
+    );
+  }
+
+  return diagnostics;
+}
+
 /**
  * @returns {PatramRepoConfig}
  */
@@ -225,7 +407,7 @@ function createDefaultRepoConfig() {
 }
 
 /**
- * @param {{ include: string[], queries: Record<string, { where: string }>, kinds?: unknown, mappings?: unknown, relations?: unknown }} repo_config
+ * @param {{ derived_summaries?: unknown, include: string[], queries: Record<string, { where: string }>, kinds?: unknown, mappings?: unknown, relations?: unknown }} repo_config
  * @returns {PatramRepoConfig}
  */
 function normalizeRepoConfig(repo_config) {
@@ -235,6 +417,16 @@ function normalizeRepoConfig(repo_config) {
     queries: { ...repo_config.queries },
   };
 
+  if (
+    repo_config.derived_summaries !== undefined &&
+    repo_config.derived_summaries !== null
+  ) {
+    normalized_config.derived_summaries =
+      /** @type {PatramRepoConfig['derived_summaries']} */ (
+        repo_config.derived_summaries
+      );
+  }
+
   if (repo_config.kinds !== undefined && repo_config.kinds !== null) {
     normalized_config.kinds = /** @type {PatramRepoConfig['kinds']} */ (
       repo_config.kinds
@@ -256,6 +448,213 @@ function normalizeRepoConfig(repo_config) {
   return normalized_config;
 }
 
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {Map<string, string>} kind_coverage
+ * @param {string[]} kind_names
+ * @param {string} summary_name
+ */
+function collectDuplicateKindDiagnostics(
+  diagnostics,
+  kind_coverage,
+  kind_names,
+  summary_name,
+) {
+  for (const kind_name of kind_names) {
+    const existing_summary_name = kind_coverage.get(kind_name);
+
+    if (!existing_summary_name) {
+      kind_coverage.set(kind_name, summary_name);
+      continue;
+    }
+
+    diagnostics.push(
+      createConfigDiagnostic(
+        `derived_summaries.${summary_name}.kinds`,
+        `Kind "${kind_name}" is already covered by derived summary "${existing_summary_name}".`,
+      ),
+    );
+  }
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {Set<string>} known_relation_names
+ * @param {string} summary_name
+ * @param {import('./load-patram-config.types.ts').DerivedSummaryFieldConfig[]} field_definitions
+ */
+function collectDerivedSummaryFieldDiagnostics(
+  diagnostics,
+  known_relation_names,
+  summary_name,
+  field_definitions,
+) {
+  for (const [field_index, field_definition] of field_definitions.entries()) {
+    if ('count' in field_definition) {
+      collectTraversalDiagnostic(
+        diagnostics,
+        field_definition.count.traversal,
+        known_relation_names,
+        `derived_summaries.${summary_name}.fields.${field_index}.count.traversal`,
+      );
+      collectWhereClauseDiagnostics(
+        diagnostics,
+        field_definition.count.where,
+        known_relation_names,
+        `derived_summaries.${summary_name}.fields.${field_index}.count.where`,
+      );
+      continue;
+    }
+
+    for (const [case_index, select_case] of field_definition.select.entries()) {
+      collectWhereClauseDiagnostics(
+        diagnostics,
+        select_case.when,
+        known_relation_names,
+        `derived_summaries.${summary_name}.fields.${field_index}.select.${case_index}.when`,
+      );
+    }
+  }
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} traversal_text
+ * @param {Set<string>} known_relation_names
+ * @param {string} diagnostic_path
+ */
+function collectTraversalDiagnostic(
+  diagnostics,
+  traversal_text,
+  known_relation_names,
+  diagnostic_path,
+) {
+  const traversal_match =
+    /^(?<direction>in|out):(?<relation_name>[a-zA-Z0-9_]+)$/du.exec(
+      traversal_text,
+    );
+
+  if (!traversal_match?.groups?.relation_name) {
+    diagnostics.push(
+      createConfigDiagnostic(
+        diagnostic_path,
+        'Derived summary traversal must use "in:<relation>" or "out:<relation>".',
+      ),
+    );
+
+    return;
+  }
+
+  if (known_relation_names.has(traversal_match.groups.relation_name)) {
+    return;
+  }
+
+  diagnostics.push(
+    createConfigDiagnostic(
+      diagnostic_path,
+      `Unknown relation "${traversal_match.groups.relation_name}" in derived summary traversal.`,
+    ),
+  );
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} where_clause
+ * @param {Set<string>} known_relation_names
+ * @param {string} diagnostic_path
+ */
+function collectWhereClauseDiagnostics(
+  diagnostics,
+  where_clause,
+  known_relation_names,
+  diagnostic_path,
+) {
+  const parse_result = parseWhereClause(where_clause);
+
+  if (!parse_result.success) {
+    diagnostics.push(
+      createConfigDiagnostic(diagnostic_path, parse_result.diagnostic.message),
+    );
+
+    return;
+  }
+
+  for (const clause of parse_result.clauses) {
+    collectClauseRelationDiagnostics(
+      diagnostics,
+      clause.term,
+      known_relation_names,
+      diagnostic_path,
+    );
+  }
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {import('./parse-where-clause.types.ts').ParsedTerm} term
+ * @param {Set<string>} known_relation_names
+ * @param {string} diagnostic_path
+ */
+function collectClauseRelationDiagnostics(
+  diagnostics,
+  term,
+  known_relation_names,
+  diagnostic_path,
+) {
+  if (term.kind === 'aggregate') {
+    if (!known_relation_names.has(term.traversal.relation_name)) {
+      diagnostics.push(
+        createConfigDiagnostic(
+          diagnostic_path,
+          `Unknown relation "${term.traversal.relation_name}" in traversal clause.`,
+        ),
+      );
+    }
+
+    for (const nested_clause of term.clauses) {
+      collectClauseRelationDiagnostics(
+        diagnostics,
+        nested_clause.term,
+        known_relation_names,
+        diagnostic_path,
+      );
+    }
+
+    return;
+  }
+
+  if (term.kind !== 'relation' && term.kind !== 'relation_target') {
+    return;
+  }
+
+  if (known_relation_names.has(term.relation_name)) {
+    return;
+  }
+
+  diagnostics.push(
+    createConfigDiagnostic(
+      diagnostic_path,
+      `Unknown relation "${term.relation_name}" in relation clause.`,
+    ),
+  );
+}
+
+/**
+ * @param {string} issue_path
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */
+function createConfigDiagnostic(issue_path, message) {
+  return {
+    code: 'config.invalid',
+    column: 1,
+    level: 'error',
+    line: 1,
+    message: `Invalid config at "${issue_path}": ${message}`,
+    path: CONFIG_FILE_NAME,
+  };
+}
+
 /**
  * @param {unknown} error
  * @returns {error is NodeJS.ErrnoException}

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

@@ -8,7 +8,38 @@ export interface StoredQueryConfig {
   where: string;
 }
 
+export type DerivedSummaryScalar = boolean | number | string | null;
+
+export interface DerivedSummaryCountFieldConfig {
+  count: {
+    traversal: string;
+    where: string;
+  };
+  name: string;
+}
+
+export interface DerivedSummarySelectCaseConfig {
+  value: DerivedSummaryScalar;
+  when: string;
+}
+
+export interface DerivedSummarySelectFieldConfig {
+  default: DerivedSummaryScalar;
+  name: string;
+  select: DerivedSummarySelectCaseConfig[];
+}
+
+export type DerivedSummaryFieldConfig =
+  | DerivedSummaryCountFieldConfig
+  | DerivedSummarySelectFieldConfig;
+
+export interface DerivedSummaryConfig {
+  fields: DerivedSummaryFieldConfig[];
+  kinds: string[];
+}
+
 export interface PatramRepoConfig {
+  derived_summaries?: Record<string, DerivedSummaryConfig>;
   include: string[];
   kinds?: Record<string, KindDefinition>;
   mappings?: Record<string, MappingDefinition>;

package/lib/output-view.types.ts

@@ -1,5 +1,17 @@
 import type { GraphNode } from './build-graph.types.ts';
 
+export type OutputDerivedValue = boolean | number | string | null;
+
+export interface OutputDerivedField {
+  name: string;
+  value: OutputDerivedValue;
+}
+
+export interface OutputDerivedSummary {
+  fields: OutputDerivedField[];
+  name: string;
+}
+
 export interface OutputViewSummary {
   count: number;
   kind: 'resolved_link_list' | 'result_list' | 'stored_query_list';
@@ -13,6 +25,7 @@ export interface QueryOutputViewSummary extends OutputViewSummary {
 }
 
 export interface OutputNodeItem {
+  derived_summary?: OutputDerivedSummary;
   id: string;
   kind: 'node';
   node_kind: GraphNode['kind'];
@@ -28,6 +41,7 @@ export interface OutputStoredQueryItem {
 }
 
 export interface OutputResolvedLinkTarget {
+  derived_summary?: OutputDerivedSummary;
   kind?: string;
   path: string;
   status?: string;
@@ -57,6 +71,7 @@ export interface QueriesOutputView {
 
 export interface ShowOutputView {
   command: 'show';
+  document?: OutputNodeItem;
   hints: string[];
   items: OutputResolvedLinkItem[];
   path: string;