patram 0.2.0 → 0.3.0

package/lib/query-inspection.js

@@ -1,3 +1,4 @@
+/** @import * as $k$$l$parse$j$where$j$clause$k$types$k$ts from './parse-where-clause.types.ts'; */
 /* eslint-disable max-lines */
 /**
  * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
@@ -19,6 +20,10 @@ import { parseWhereClause } from './parse-where-clause.js';
  * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
  */
 
+/**
+ * @typedef {import('./parse-where-clause.types.ts').ParsedFieldTerm | import('./parse-where-clause.types.ts').ParsedFieldSetTerm} FieldDiagnosticTerm
+ */
+
 /**
  * @typedef {{ query_source: QuerySource, where_clause: string }} ResolvedWhereClause
  */
@@ -67,7 +72,7 @@ export function inspectQuery(
     };
   }
 
-  const diagnostics = collectRelationDiagnostics(
+  const diagnostics = getQuerySemanticDiagnostics(
     repo_config,
     resolved_where_clause.query_source,
     parse_result.clauses,
@@ -143,12 +148,10 @@ export function renderQueryInspection(query_inspection, output_mode) {
  * @param {ParsedClause[]} clauses
  * @returns {PatramDiagnostic[]}
  */
-function collectRelationDiagnostics(repo_config, query_source, clauses) {
-  if (!repo_config.relations) {
-    return [];
-  }
-
-  const known_relation_names = new Set(Object.keys(repo_config.relations));
+function collectSemanticDiagnostics(repo_config, query_source, clauses) {
+  const known_relation_names = new Set(
+    Object.keys(repo_config.relations ?? {}),
+  );
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
 
@@ -156,22 +159,41 @@ function collectRelationDiagnostics(repo_config, query_source, clauses) {
     clauses,
     diagnostics,
     known_relation_names,
+    repo_config.fields ?? {},
     formatQueryDiagnosticPath(query_source),
   );
 
   return diagnostics;
 }
 
+/**
+ * Collect schema-aware diagnostics for one parsed where clause.
+ *
+ * @param {PatramRepoConfig} repo_config
+ * @param {QuerySource} query_source
+ * @param {ParsedClause[]} clauses
+ * @returns {PatramDiagnostic[]}
+ */
+export function getQuerySemanticDiagnostics(
+  repo_config,
+  query_source,
+  clauses,
+) {
+  return collectSemanticDiagnostics(repo_config, query_source, clauses);
+}
+
 /**
  * @param {ParsedClause[]} clauses
  * @param {PatramDiagnostic[]} diagnostics
  * @param {Set<string>} known_relation_names
+ * @param {Record<string, import('./load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
  * @param {string} diagnostic_path
  */
 function collectClauseDiagnostics(
   clauses,
   diagnostics,
   known_relation_names,
+  known_field_definitions,
   diagnostic_path,
 ) {
   for (const clause of clauses) {
@@ -179,6 +201,7 @@ function collectClauseDiagnostics(
       clause.term,
       diagnostics,
       known_relation_names,
+      known_field_definitions,
       diagnostic_path,
     );
   }
@@ -188,12 +211,14 @@ function collectClauseDiagnostics(
  * @param {ParsedTerm} term
  * @param {PatramDiagnostic[]} diagnostics
  * @param {Set<string>} known_relation_names
+ * @param {Record<string, import('./load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
  * @param {string} diagnostic_path
  */
 function collectTermDiagnostics(
   term,
   diagnostics,
   known_relation_names,
+  known_field_definitions,
   diagnostic_path,
 ) {
   if (term.kind === 'aggregate') {
@@ -207,6 +232,7 @@ function collectTermDiagnostics(
       term.clauses,
       diagnostics,
       known_relation_names,
+      known_field_definitions,
       diagnostic_path,
     );
 
@@ -233,7 +259,256 @@ function collectTermDiagnostics(
       diagnostic_path,
       'relation clause',
     );
+
+    return;
+  }
+
+  collectFieldDiagnostics(
+    /** @type {FieldDiagnosticTerm} */ (term),
+    diagnostics,
+    known_field_definitions,
+    diagnostic_path,
+  );
+}
+
+/**
+ * @param {FieldDiagnosticTerm} term
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {Record<string, import('./load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
+ * @param {string} diagnostic_path
+ */
+function collectFieldDiagnostics(
+  term,
+  diagnostics,
+  known_field_definitions,
+  diagnostic_path,
+) {
+  const field_diagnostics_collector = getFieldDiagnosticsCollector(
+    term.field_name,
+  );
+
+  if (field_diagnostics_collector) {
+    field_diagnostics_collector(term, diagnostics, diagnostic_path);
+    return;
+  }
+
+  if (term.field_name.startsWith('$')) {
+    diagnostics.push(
+      createQueryDiagnostic(
+        diagnostic_path,
+        term.column,
+        `Reserved field "${term.field_name}" is not available.`,
+        'query.reserved_field',
+      ),
+    );
+
+    return;
   }
+
+  const field_definition = known_field_definitions[term.field_name];
+
+  if (!field_definition) {
+    diagnostics.push(
+      createQueryDiagnostic(
+        diagnostic_path,
+        term.column,
+        `Unknown field "${term.field_name}".`,
+        'query.unknown_field',
+      ),
+    );
+
+    return;
+  }
+
+  if (term.kind === 'field_set') {
+    if (term.operator === 'in' || term.operator === 'not in') {
+      return;
+    }
+  }
+
+  if (term.kind === 'field') {
+    const operator_diagnostic = getMetadataFieldOperatorDiagnostic(
+      term,
+      field_definition,
+      diagnostic_path,
+    );
+
+    if (operator_diagnostic) {
+      diagnostics.push(operator_diagnostic);
+    }
+  }
+}
+
+/**
+ * @param {string} field_name
+ * @returns {((term: FieldDiagnosticTerm, diagnostics: PatramDiagnostic[], diagnostic_path: string) => void) | null}
+ */
+function getFieldDiagnosticsCollector(field_name) {
+  if (field_name === 'title') {
+    return collectTitleFieldDiagnostics;
+  }
+
+  if (
+    field_name === '$id' ||
+    field_name === '$class' ||
+    field_name === '$path'
+  ) {
+    return collectStructuralFieldDiagnostics;
+  }
+
+  return null;
+}
+
+/**
+ * @param {FieldDiagnosticTerm} term
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} diagnostic_path
+ */
+function collectTitleFieldDiagnostics(term, diagnostics, diagnostic_path) {
+  const operator = term.kind === 'field' ? term.operator : term.operator;
+  const allowed = new Set(['=', '!=', 'in', 'not in', '~']);
+
+  if (allowed.has(operator)) {
+    return;
+  }
+
+  diagnostics.push(
+    createQueryDiagnostic(
+      diagnostic_path,
+      term.column,
+      `Field "title" does not support the "${operator}" operator.`,
+      'query.invalid_operator',
+    ),
+  );
+}
+
+/**
+ * @param {FieldDiagnosticTerm} term
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} diagnostic_path
+ */
+function collectStructuralFieldDiagnostics(term, diagnostics, diagnostic_path) {
+  const operator = term.kind === 'field' ? term.operator : term.operator;
+  const allowed_by_field = new Map([
+    ['$class', new Set(['=', '!=', 'in', 'not in'])],
+    ['$id', new Set(['=', '!=', 'in', 'not in', '^='])],
+    ['$path', new Set(['=', '!=', 'in', 'not in', '^='])],
+  ]);
+  const allowed = allowed_by_field.get(term.field_name);
+
+  if (!allowed || allowed.has(operator)) {
+    return;
+  }
+
+  diagnostics.push(
+    createQueryDiagnostic(
+      diagnostic_path,
+      term.column,
+      `Field "${term.field_name}" does not support the "${operator}" operator.`,
+      'query.invalid_operator',
+    ),
+  );
+}
+
+/**
+ * @param {import('./parse-where-clause.types.ts').ParsedFieldTerm} term
+ * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @param {string} diagnostic_path
+ * @returns {PatramDiagnostic | null}
+ */
+function getMetadataFieldOperatorDiagnostic(
+  term,
+  field_definition,
+  diagnostic_path,
+) {
+  if (supportsMetadataFieldOperator(term.operator, field_definition)) {
+    return null;
+  }
+
+  return createQueryDiagnostic(
+    diagnostic_path,
+    term.column,
+    getUnsupportedOperatorMessage(term.field_name, term.operator),
+    'query.invalid_operator',
+  );
+}
+
+/**
+ * @param {string} operator
+ * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @returns {boolean}
+ */
+function supportsMetadataFieldOperator(operator, field_definition) {
+  if (operator === '=' || operator === '!=') {
+    return true;
+  }
+
+  if (operator === '^=') {
+    return supportsPrefixOperator(field_definition);
+  }
+
+  if (operator === '~') {
+    return supportsContainsOperator(field_definition);
+  }
+
+  return supportsOrderedComparison(operator, field_definition.type);
+}
+
+/**
+ * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @returns {boolean}
+ */
+function supportsPrefixOperator(field_definition) {
+  if (field_definition.type === 'path') {
+    return true;
+  }
+
+  return (
+    field_definition.type === 'string' &&
+    field_definition.query?.prefix === true
+  );
+}
+
+/**
+ * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @returns {boolean}
+ */
+function supportsContainsOperator(field_definition) {
+  return (
+    field_definition.type === 'string' &&
+    field_definition.query?.contains === true
+  );
+}
+
+/**
+ * @param {string} operator
+ * @param {string} field_type
+ * @returns {boolean}
+ */
+function supportsOrderedComparison(operator, field_type) {
+  if (
+    operator !== '<' &&
+    operator !== '<=' &&
+    operator !== '>' &&
+    operator !== '>='
+  ) {
+    return false;
+  }
+
+  return (
+    field_type === 'integer' ||
+    field_type === 'date' ||
+    field_type === 'date_time'
+  );
+}
+
+/**
+ * @param {string} field_name
+ * @param {string} operator
+ * @returns {string}
+ */
+function getUnsupportedOperatorMessage(field_name, operator) {
+  return `Field "${field_name}" does not support the "${operator}" operator.`;
 }
 
 /**
@@ -290,7 +565,6 @@ function collectTraversalDiagnostic(
 
 /**
  * @param {QueryInspectionSuccess} query_inspection
- * @returns {object}
  */
 function formatJsonQueryInspection(query_inspection) {
   if (query_inspection.inspection_mode === 'lint') {
@@ -489,11 +763,12 @@ function formatQueryDiagnosticPath(query_source) {
  * @param {string} diagnostic_path
  * @param {number} column
  * @param {string} message
+ * @param {PatramDiagnostic['code']} [code]
  * @returns {PatramDiagnostic}
  */
-function createQueryDiagnostic(diagnostic_path, column, message) {
+function createQueryDiagnostic(diagnostic_path, column, message, code) {
   return {
-    code: 'query.unknown_relation',
+    code: code ?? 'query.unknown_relation',
     column,
     level: 'error',
     line: 1,

package/lib/render-field-discovery.js

@@ -0,0 +1,148 @@
+/**
+ * @import { ResolvedOutputMode } from './output-view.types.ts';
+ * @import { FieldDiscoveryResult, FieldDiscoverySuggestion } from './discover-fields.types.ts';
+ */
+
+import { Ansis } from 'ansis';
+
+/**
+ * Render field discovery output.
+ *
+ * @param {FieldDiscoveryResult} discovery_result
+ * @param {ResolvedOutputMode} output_mode
+ * @returns {string}
+ */
+export function renderFieldDiscovery(discovery_result, output_mode) {
+  if (output_mode.renderer_name === 'json') {
+    return `${JSON.stringify(formatJsonFieldDiscovery(discovery_result), null, 2)}\n`;
+  }
+
+  return renderTextFieldDiscovery(discovery_result, output_mode);
+}
+
+/**
+ * @param {FieldDiscoveryResult} discovery_result
+ * @returns {{ fields: Array<Record<string, unknown>>, summary: FieldDiscoveryResult['summary'] }}
+ */
+function formatJsonFieldDiscovery(discovery_result) {
+  return {
+    fields: discovery_result.fields.map(formatJsonFieldSuggestion),
+    summary: discovery_result.summary,
+  };
+}
+
+/**
+ * @param {FieldDiscoverySuggestion} field_suggestion
+ * @returns {Record<string, unknown>}
+ */
+function formatJsonFieldSuggestion(field_suggestion) {
+  return {
+    confidence: field_suggestion.confidence,
+    conflicting_evidence: field_suggestion.conflicting_evidence,
+    evidence_references: field_suggestion.evidence_references,
+    likely_class_usage: field_suggestion.likely_class_usage,
+    likely_multiplicity: field_suggestion.likely_multiplicity,
+    likely_type: field_suggestion.likely_type,
+    name: field_suggestion.name,
+  };
+}
+
+/**
+ * @param {FieldDiscoveryResult} discovery_result
+ * @param {ResolvedOutputMode} output_mode
+ * @returns {string}
+ */
+function renderTextFieldDiscovery(discovery_result, output_mode) {
+  const ansi = new Ansis(
+    output_mode.renderer_name === 'rich' && output_mode.color_enabled ? 3 : 0,
+  );
+  /** @type {string[]} */
+  const output_lines = [];
+
+  output_lines.push(
+    output_mode.renderer_name === 'rich'
+      ? ansi.green('Field discovery')
+      : 'Field discovery',
+  );
+
+  output_lines.push(
+    output_mode.renderer_name === 'rich'
+      ? ansi.gray(
+          `Found ${discovery_result.summary.count} suggested fields from ${discovery_result.summary.source_file_count} source files.`,
+        )
+      : `Found ${discovery_result.summary.count} suggested fields from ${discovery_result.summary.source_file_count} source files.`,
+  );
+
+  for (const field_suggestion of discovery_result.fields) {
+    output_lines.push(
+      '',
+      ...formatTextFieldSuggestion(field_suggestion, {
+        header: (value) =>
+          output_mode.renderer_name === 'rich' ? ansi.green(value) : value,
+        label: (value) =>
+          output_mode.renderer_name === 'rich' ? ansi.gray(value) : value,
+      }),
+    );
+  }
+
+  if (discovery_result.fields.length === 0) {
+    output_lines.push('', 'No field candidates discovered.');
+  }
+
+  return `${output_lines.join('\n')}\n`;
+}
+
+/**
+ * @param {FieldDiscoverySuggestion} field_suggestion
+ * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
+ * @returns {string[]}
+ */
+function formatTextFieldSuggestion(field_suggestion, render_options) {
+  /** @type {string[]} */
+  const lines = [render_options.header(field_suggestion.name)];
+
+  lines.push(
+    `${render_options.label('  likely type:')} ${field_suggestion.likely_type.name}`,
+    `${render_options.label('  likely multiplicity:')} ${field_suggestion.likely_multiplicity.name}`,
+    `${render_options.label('  likely class usage:')} ${field_suggestion.likely_class_usage.classes.join(', ')}`,
+    `${render_options.label('  confidence:')} ${formatConfidence(field_suggestion.confidence)}`,
+  );
+
+  if (field_suggestion.evidence_references.length > 0) {
+    lines.push(render_options.label('  evidence:'));
+    lines.push(
+      ...field_suggestion.evidence_references.map(
+        (evidence_reference) =>
+          `${render_options.label('    ')}${formatEvidenceReference(evidence_reference)}`,
+      ),
+    );
+  }
+
+  if (field_suggestion.conflicting_evidence.length > 0) {
+    lines.push(render_options.label('  conflicting evidence:'));
+    lines.push(
+      ...field_suggestion.conflicting_evidence.map(
+        (evidence_reference) =>
+          `${render_options.label('    ')}${formatEvidenceReference(evidence_reference)}`,
+      ),
+    );
+  }
+
+  return lines;
+}
+
+/**
+ * @param {import('./discover-fields.types.ts').FieldDiscoveryEvidenceReference} evidence_reference
+ * @returns {string}
+ */
+function formatEvidenceReference(evidence_reference) {
+  return `${evidence_reference.path}:${evidence_reference.line}:${evidence_reference.column} ${JSON.stringify(evidence_reference.value)}`;
+}
+
+/**
+ * @param {number} confidence
+ * @returns {string}
+ */
+function formatConfidence(confidence) {
+  return confidence.toFixed(2);
+}

package/lib/render-json-output.js

@@ -55,19 +55,19 @@ export function renderJsonOutput(output_view) {
 
 /**
  * @param {OutputNodeItem} output_item
- * @returns {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, id: string, kind: string, title: string, path: string, status?: string }}
+ * @returns {{ '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string }}
  */
 function formatJsonQueryItem(output_item) {
-  /** @type {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, id: string, kind: string, title: string, path: string, status?: string }} */
+  /** @type {{ '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string }} */
   const query_item = {
-    id: output_item.id,
-    kind: output_item.node_kind,
+    $class: output_item.node_kind,
+    $id: output_item.id,
+    fields: output_item.fields,
     title: output_item.title,
-    path: output_item.path,
   };
 
-  if (output_item.status) {
-    query_item.status = output_item.status;
+  if (output_item.path) {
+    query_item.$path = output_item.path;
   }
 
   if (output_item.derived_summary) {
@@ -96,25 +96,23 @@ function formatJsonStoredQuery(output_item) {
 
 /**
  * @param {OutputResolvedLinkItem} output_item
- * @returns {{ label: string, reference: number, target: { derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind?: string, path: string, status?: string, title: string } }}
+ * @returns {{ label: string, reference: number, target: { '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string } }}
  */
 function formatJsonResolvedLink(output_item) {
-  /** @type {{ label: string, reference: number, target: { derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind?: string, path: string, status?: string, title: string } }} */
+  /** @type {{ label: string, reference: number, target: { '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string } }} */
   const resolved_link = {
     reference: output_item.reference,
     label: output_item.label,
     target: {
+      $class: output_item.target.kind,
+      $id: output_item.target.id,
+      fields: output_item.target.fields,
       title: output_item.target.title,
-      path: output_item.target.path,
     },
   };
 
-  if (output_item.target.kind) {
-    resolved_link.target.kind = output_item.target.kind;
-  }
-
-  if (output_item.target.status) {
-    resolved_link.target.status = output_item.target.status;
+  if (output_item.target.path) {
+    resolved_link.target.$path = output_item.target.path;
   }
 
   if (output_item.target.derived_summary) {
@@ -133,18 +131,19 @@ function formatJsonResolvedLink(output_item) {
 
 /**
  * @param {OutputNodeItem} output_item
- * @returns {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind: string, title: string, path: string, status?: string }}
+ * @returns {{ '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string }}
  */
 function formatJsonShowDocument(output_item) {
-  /** @type {{ derived?: Record<string, boolean | number | string | null>, derived_summary?: string, kind: string, title: string, path: string, status?: string }} */
+  /** @type {{ '$class': string, '$id': string, '$path'?: string, derived?: Record<string, boolean | number | string | null>, derived_summary?: string, fields: Record<string, string | string[]>, title: string }} */
   const document_summary = {
-    kind: output_item.node_kind,
-    path: output_item.path,
+    $class: output_item.node_kind,
+    $id: output_item.id,
+    fields: output_item.fields,
     title: output_item.title,
   };
 
-  if (output_item.status) {
-    document_summary.status = output_item.status;
+  if (output_item.path) {
+    document_summary.$path = output_item.path;
   }
 
   if (output_item.derived_summary) {