patram 0.3.0 → 0.5.0

package/lib/parse-claims.js

@@ -1,6 +1,5 @@
-/** @import * as $k$$l$parse$j$claims$k$types$k$ts from './parse-claims.types.ts'; */
 /**
- * @import { ParseClaimsInput, ParseSourceFileResult } from './parse-claims.types.ts';
+ * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaim } from './parse-claims.types.ts';
  */
 
 import { getFileExtension } from './claim-helpers.js';
@@ -51,7 +50,7 @@ export function parseSourceFile(parse_input) {
  * Parse a file into neutral Patram claims.
  *
  * @param {ParseClaimsInput} parse_input
- * @returns {$k$$l$parse$j$claims$k$types$k$ts.PatramClaim[]}
+ * @returns {PatramClaim[]}
  */
 export function parseClaims(parse_input) {
   return parseSourceFile(parse_input).claims;

package/lib/parse-jsdoc-claims.js

@@ -1,6 +1,6 @@
-/** @import * as $k$$l$load$j$patram$j$config$k$types$k$ts from './load-patram-config.types.ts'; */
 /**
- * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaim, PatramClaimFields } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaimFields } from './parse-claims.types.ts';
  */
 
 import {
@@ -266,7 +266,7 @@ function compareClaimEntries(left_entry, right_entry) {
 /**
  * @param {string} file_path
  * @param {{ activation_column: number | null, activation_line: number | null }} jsdoc_block
- * @returns {$k$$l$load$j$patram$j$config$k$types$k$ts.PatramDiagnostic}
+ * @returns {PatramDiagnostic}
  */
 function createMultiplePatramBlocksDiagnostic(file_path, jsdoc_block) {
   return {

package/lib/parse-where-clause.js

@@ -6,7 +6,7 @@
  *   ParsedAggregateComparison,
  *   ParsedAggregateName,
  *   ParsedAggregateTerm,
- *   ParsedClause,
+ *   ParsedExpression,
  *   ParsedFieldName,
  *   ParsedTerm,
  *   ParsedTraversalTerm,
@@ -17,6 +17,16 @@
  * @typedef {{ index: number, where_clause: string }} ParserState
  */
 
+/**
+ * @typedef {{
+ *   expression: ParsedExpression,
+ *   success: true,
+ * } | {
+ *   diagnostic: PatramDiagnostic,
+ *   success: false,
+ * }} ParseExpressionResult
+ */
+
 /**
  * @typedef {{
  *   success: true,
@@ -28,7 +38,7 @@
  */
 
 /**
- * Parse one where clause into structured clauses.
+ * Parse one where clause into a structured boolean expression.
  *
  * @param {string} where_clause
  * @returns {ParseWhereClauseResult}
@@ -43,10 +53,10 @@ export function parseWhereClause(where_clause) {
     return fail(1, 'Query must not be empty.');
   }
 
-  const clauses_result = parseClauses(parser_state, null);
+  const expression_result = parseExpression(parser_state, null);
 
-  if (!clauses_result.success) {
-    return clauses_result;
+  if (!expression_result.success) {
+    return expression_result;
   }
 
   skipWhitespace(parser_state);
@@ -56,7 +66,7 @@ export function parseWhereClause(where_clause) {
   }
 
   return {
-    clauses: clauses_result.clauses,
+    expression: expression_result.expression,
     success: true,
   };
 }
@@ -64,12 +74,29 @@ export function parseWhereClause(where_clause) {
 /**
  * @param {ParserState} parser_state
  * @param {')' | null} stop_character
- * @returns {ParseWhereClauseResult}
+ * @returns {ParseExpressionResult}
  */
-function parseClauses(parser_state, stop_character) {
-  /** @type {ParsedClause[]} */
-  const clauses = [];
-  let is_first_clause = true;
+function parseExpression(parser_state, stop_character) {
+  return parseOrExpression(parser_state, stop_character);
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @param {')' | null} stop_character
+ * @returns {ParseExpressionResult}
+ */
+function parseOrExpression(parser_state, stop_character) {
+  const first_expression_result = parseAndExpression(
+    parser_state,
+    stop_character,
+  );
+
+  if (!first_expression_result.success) {
+    return first_expression_result;
+  }
+
+  /** @type {ParsedExpression[]} */
+  const expressions = [first_expression_result.expression];
 
   while (true) {
     skipWhitespace(parser_state);
@@ -78,68 +105,185 @@ function parseClauses(parser_state, stop_character) {
       currentCharacter(parser_state) === stop_character ||
       isAtEnd(parser_state)
     ) {
-      return is_first_clause
-        ? fail(parser_state.where_clause.length + 1, 'Expected a query term.')
-        : { clauses, success: true };
+      return collapseBooleanExpression('or', expressions);
     }
 
-    if (!is_first_clause) {
-      if (!consumeKeyword(parser_state, 'and')) {
-        return failToken(parser_state);
-      }
-
-      skipWhitespace(parser_state);
-
-      if (
-        currentCharacter(parser_state) === stop_character ||
-        isAtEnd(parser_state)
-      ) {
-        return fail(
-          parser_state.where_clause.length + 1,
-          'Expected a query term.',
-        );
-      }
+    if (!consumeKeyword(parser_state, 'or')) {
+      return collapseBooleanExpression('or', expressions);
     }
 
-    const clause_result = parseClause(parser_state);
+    skipWhitespace(parser_state);
 
-    if (!clause_result.success) {
-      return clause_result;
+    if (
+      currentCharacter(parser_state) === stop_character ||
+      isAtEnd(parser_state)
+    ) {
+      return failExpectedTerm(parser_state);
     }
 
-    clauses.push(clause_result.clause);
-    is_first_clause = false;
+    const next_expression_result = parseAndExpression(
+      parser_state,
+      stop_character,
+    );
+
+    if (!next_expression_result.success) {
+      return next_expression_result;
+    }
+
+    expressions.push(next_expression_result.expression);
   }
 }
 
 /**
  * @param {ParserState} parser_state
- * @returns {{ clause: ParsedClause, success: true } | { diagnostic: PatramDiagnostic, success: false }}
+ * @param {')' | null} stop_character
+ * @returns {ParseExpressionResult}
  */
-function parseClause(parser_state) {
-  const clause_start = parser_state.index;
-  const is_negated = consumeKeyword(parser_state, 'not');
+function parseAndExpression(parser_state, stop_character) {
+  const first_expression_result = parseUnaryExpression(
+    parser_state,
+    stop_character,
+  );
+
+  if (!first_expression_result.success) {
+    return first_expression_result;
+  }
+
+  /** @type {ParsedExpression[]} */
+  const expressions = [first_expression_result.expression];
+
+  while (true) {
+    skipWhitespace(parser_state);
+
+    if (
+      currentCharacter(parser_state) === stop_character ||
+      isAtEnd(parser_state)
+    ) {
+      return collapseBooleanExpression('and', expressions);
+    }
+
+    if (!consumeKeyword(parser_state, 'and')) {
+      return collapseBooleanExpression('and', expressions);
+    }
 
-  if (is_negated && !consumeRequiredWhitespace(parser_state)) {
+    skipWhitespace(parser_state);
+
+    if (
+      currentCharacter(parser_state) === stop_character ||
+      isAtEnd(parser_state)
+    ) {
+      return failExpectedTerm(parser_state);
+    }
+
+    const next_expression_result = parseUnaryExpression(
+      parser_state,
+      stop_character,
+    );
+
+    if (!next_expression_result.success) {
+      return next_expression_result;
+    }
+
+    expressions.push(next_expression_result.expression);
+  }
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @param {')' | null} stop_character
+ * @returns {ParseExpressionResult}
+ */
+function parseUnaryExpression(parser_state, stop_character) {
+  skipWhitespace(parser_state);
+  const start_index = parser_state.index;
+
+  if (!consumeKeyword(parser_state, 'not')) {
+    return parsePrimaryExpression(parser_state, stop_character);
+  }
+
+  const whitespace_length = skipWhitespace(parser_state);
+
+  if (whitespace_length === 0 && currentCharacter(parser_state) !== '(') {
     return fail(
-      clause_start + 1,
-      `Unsupported query token "${readToken(parser_state, clause_start)}".`,
+      start_index + 1,
+      `Unsupported query token "${readToken(parser_state, start_index)}".`,
     );
   }
 
+  if (
+    currentCharacter(parser_state) === stop_character ||
+    isAtEnd(parser_state)
+  ) {
+    return failExpectedTerm(parser_state);
+  }
+
+  const expression_result = parseUnaryExpression(parser_state, stop_character);
+
+  if (!expression_result.success) {
+    return expression_result;
+  }
+
+  return successExpression({
+    expression: expression_result.expression,
+    kind: 'not',
+  });
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @param {')' | null} stop_character
+ * @returns {ParseExpressionResult}
+ */
+function parsePrimaryExpression(parser_state, stop_character) {
+  skipWhitespace(parser_state);
+
+  if (
+    currentCharacter(parser_state) === stop_character ||
+    isAtEnd(parser_state)
+  ) {
+    return failExpectedTerm(parser_state);
+  }
+
+  if (consumeOperator(parser_state, '(')) {
+    const expression_result = parseExpression(parser_state, ')');
+
+    if (!expression_result.success) {
+      return expression_result;
+    }
+
+    if (!consumeOperator(parser_state, ')')) {
+      return failToken(parser_state);
+    }
+
+    return expression_result;
+  }
+
   const term_result = parseTerm(parser_state);
 
   if (!term_result.success) {
     return term_result;
   }
 
-  return {
-    clause: {
-      is_negated,
-      term: term_result.term,
-    },
-    success: true,
-  };
+  return successExpression({
+    kind: 'term',
+    term: term_result.term,
+  });
+}
+
+/**
+ * @param {'and' | 'or'} kind
+ * @param {ParsedExpression[]} expressions
+ * @returns {ParseExpressionResult}
+ */
+function collapseBooleanExpression(kind, expressions) {
+  if (expressions.length === 1) {
+    return successExpression(expressions[0]);
+  }
+
+  return successExpression({
+    expressions,
+    kind,
+  });
 }
 
 /**
@@ -188,10 +332,10 @@ function parseAggregate(parser_state) {
   }
 
   skipWhitespace(parser_state);
-  const clauses_result = parseClauses(parser_state, ')');
+  const expression_result = parseExpression(parser_state, ')');
 
-  if (!clauses_result.success) {
-    return clauses_result;
+  if (!expression_result.success) {
+    return expression_result;
   }
 
   if (!consumeOperator(parser_state, ')')) {
@@ -202,7 +346,7 @@ function parseAggregate(parser_state) {
     parser_state,
     aggregate_name,
     traversal_result.traversal,
-    clauses_result.clauses,
+    expression_result.expression,
   );
 }
 
@@ -225,20 +369,25 @@ function parseAtomicTerm(parser_state) {
  * @param {ParserState} parser_state
  * @param {ParsedAggregateName} aggregate_name
  * @param {ParsedTraversalTerm} traversal
- * @param {ParsedClause[]} clauses
+ * @param {ParsedExpression} expression
  * @returns {ParseTermResult}
  */
-function createAggregateTerm(parser_state, aggregate_name, traversal, clauses) {
+function createAggregateTerm(
+  parser_state,
+  aggregate_name,
+  traversal,
+  expression,
+) {
   /** @type {ParsedAggregateTerm} */
   const aggregate_term = {
     aggregate_name,
-    clauses,
+    expression,
     kind: 'aggregate',
     traversal,
   };
 
   if (aggregate_name !== 'count') {
-    return success(aggregate_term);
+    return successTerm(aggregate_term);
   }
 
   const count_tail = parseCountTail(parser_state);
@@ -247,7 +396,7 @@ function createAggregateTerm(parser_state, aggregate_name, traversal, clauses) {
     return failToken(parser_state);
   }
 
-  return success({
+  return successTerm({
     ...aggregate_term,
     comparison: count_tail.comparison,
     value: count_tail.value,
@@ -262,6 +411,7 @@ function createAggregateTerm(parser_state, aggregate_name, traversal, clauses) {
  */
 function parseFieldSet(parser_state, start_index, field_name) {
   const operator_start_index = parser_state.index;
+
   if (!consumeRequiredWhitespace(parser_state)) {
     return null;
   }
@@ -280,7 +430,7 @@ function parseFieldSet(parser_state, start_index, field_name) {
   const values = parseList(parser_state);
 
   return values
-    ? success({
+    ? successTerm({
         column: start_index + 1,
         field_name,
         kind: 'field_set',
@@ -348,7 +498,7 @@ function parseOperatorTerm(parser_state, start_index, field_or_relation_name) {
   }
 
   if (consumeOperator(parser_state, ':*')) {
-    return success({
+    return successTerm({
       column: start_index + 1,
       kind: 'relation',
       relation_name: field_or_relation_name,
@@ -435,7 +585,7 @@ function parsePrefixTerm(parser_state, start_index, field_name) {
   const value = parseBareValue(parser_state);
 
   return value
-    ? success({
+    ? successTerm({
         column: start_index + 1,
         field_name,
         kind: 'field',
@@ -460,7 +610,7 @@ function parseContainsTerm(parser_state, start_index, field_name) {
   const value = parseBareValue(parser_state);
 
   return value
-    ? success({
+    ? successTerm({
         column: start_index + 1,
         field_name,
         kind: 'field',
@@ -493,7 +643,7 @@ function parseEqualityTerm(parser_state, start_index, field_or_relation_name) {
     field_or_relation_name === 'title' ||
     !value.includes(':')
   ) {
-    return success({
+    return successTerm({
       column: start_index + 1,
       field_name: field_or_relation_name,
       kind: 'field',
@@ -502,7 +652,7 @@ function parseEqualityTerm(parser_state, start_index, field_or_relation_name) {
     });
   }
 
-  return success({
+  return successTerm({
     column: start_index + 1,
     kind: 'relation_target',
     relation_name: field_or_relation_name,
@@ -530,7 +680,7 @@ function parseFieldComparisonTerm(parser_state, start_index, field_name) {
     return failToken(parser_state);
   }
 
-  return success({
+  return successTerm({
     column: start_index + 1,
     field_name,
     kind: 'field',
@@ -725,11 +875,19 @@ function isAtEnd(parser_state) {
   return parser_state.index >= parser_state.where_clause.length;
 }
 
+/**
+ * @param {ParsedExpression} expression
+ * @returns {ParseExpressionResult}
+ */
+function successExpression(expression) {
+  return { expression, success: true };
+}
+
 /**
  * @param {ParsedTerm} term
  * @returns {ParseTermResult}
  */
-function success(term) {
+function successTerm(term) {
   return { success: true, term };
 }
 
@@ -744,6 +902,19 @@ function failToken(parser_state) {
   );
 }
 
+/**
+ * @param {ParserState} parser_state
+ * @returns {{ diagnostic: PatramDiagnostic, success: false }}
+ */
+function failExpectedTerm(parser_state) {
+  return fail(
+    isAtEnd(parser_state)
+      ? parser_state.where_clause.length + 1
+      : parser_state.index + 1,
+    'Expected a query term.',
+  );
+}
+
 /**
  * @param {number} column
  * @param {string} message

package/lib/parse-where-clause.types.ts

@@ -42,13 +42,28 @@ export type ParsedAggregateName = 'any' | 'count' | 'none';
 
 export interface ParsedAggregateTerm {
   aggregate_name: ParsedAggregateName;
-  clauses: ParsedClause[];
   comparison?: ParsedAggregateComparison;
+  expression: ParsedExpression;
   kind: 'aggregate';
   traversal: ParsedTraversalTerm;
   value?: number;
 }
 
+export interface ParsedTermExpression {
+  kind: 'term';
+  term: ParsedTerm;
+}
+
+export interface ParsedNotExpression {
+  expression: ParsedExpression;
+  kind: 'not';
+}
+
+export interface ParsedBooleanExpression {
+  expressions: ParsedExpression[];
+  kind: 'and' | 'or';
+}
+
 export type ParsedTerm =
   | ParsedAggregateTerm
   | ParsedFieldSetTerm
@@ -56,14 +71,14 @@ export type ParsedTerm =
   | ParsedRelationTargetTerm
   | ParsedRelationTerm;
 
-export interface ParsedClause {
-  is_negated: boolean;
-  term: ParsedTerm;
-}
+export type ParsedExpression =
+  | ParsedBooleanExpression
+  | ParsedNotExpression
+  | ParsedTermExpression;
 
 export type ParseWhereClauseResult =
   | {
-      clauses: ParsedClause[];
+      expression: ParsedExpression;
       success: true;
     }
   | {

package/lib/patram-cli.js

@@ -9,6 +9,7 @@ import { checkGraph } from './check-graph.js';
 import {
   shouldPageCommandOutput,
   writeCommandOutput,
+  writeRenderedCommandOutput,
 } from './command-output.js';
 import { discoverFields } from './discover-fields.js';
 import { listRepoFiles } from './list-source-files.js';
@@ -257,9 +258,20 @@ async function runFieldsCommand(parsed_command, io_context) {
     no_color: process.env.NO_COLOR !== undefined,
     term: process.env.TERM,
   });
-  const discovery_result = await discoverFields(process.cwd());
+  const load_result = await loadPatramConfig(process.cwd());
+  const defined_field_names =
+    load_result.diagnostics.length === 0
+      ? collectDefinedDiscoveryNames(load_result.config)
+      : new Set();
+  const discovery_result = await discoverFields(process.cwd(), {
+    defined_field_names,
+  });
 
-  io_context.stdout.write(renderFieldDiscovery(discovery_result, output_mode));
+  await writeRenderedCommandOutput(
+    io_context,
+    parsed_command,
+    renderFieldDiscovery(discovery_result, output_mode),
+  );
 
   return 0;
 }
@@ -395,6 +407,7 @@ async function runShowCommand(parsed_command, io_context) {
     parsed_command,
     createShowOutputView(show_output.value, {
       derived_summary_evaluator,
+      document_node_ids: project_graph_result.graph.document_node_ids,
       graph_nodes: project_graph_result.graph.nodes,
       repo_config: project_graph_result.config,
     }),
@@ -494,3 +507,22 @@ function createQueryExecutionOptions(parsed_command, use_pager) {
 function formatDiagnostic(diagnostic) {
   return `${diagnostic.path}:${diagnostic.line}:${diagnostic.column} ${diagnostic.level} ${diagnostic.code} ${diagnostic.message}\n`;
 }
+
+/**
+ * @param {import('./load-patram-config.types.ts').PatramRepoConfig | null} repo_config
+ * @returns {Set<string>}
+ */
+function collectDefinedDiscoveryNames(repo_config) {
+  /** @type {Set<string>} */
+  const defined_field_names = new Set();
+
+  for (const field_name of Object.keys(repo_config?.fields ?? {})) {
+    defined_field_names.add(field_name);
+  }
+
+  for (const relation_name of Object.keys(repo_config?.relations ?? {})) {
+    defined_field_names.add(relation_name);
+  }
+
+  return defined_field_names;
+}