patram 0.1.1 → 0.2.0

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

@@ -0,0 +1,70 @@
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+
+export type ParsedFieldName = 'id' | 'kind' | 'path' | 'status' | 'title';
+
+export interface ParsedFieldTerm {
+  field_name: ParsedFieldName;
+  kind: 'field';
+  operator: '=' | '^=' | '~';
+  value: string;
+}
+
+export interface ParsedFieldSetTerm {
+  field_name: ParsedFieldName;
+  kind: 'field_set';
+  operator: 'in' | 'not in';
+  values: string[];
+}
+
+export interface ParsedTraversalTerm {
+  column: number;
+  direction: 'in' | 'out';
+  relation_name: string;
+}
+
+export interface ParsedRelationTerm {
+  column: number;
+  kind: 'relation';
+  relation_name: string;
+}
+
+export interface ParsedRelationTargetTerm {
+  column: number;
+  kind: 'relation_target';
+  relation_name: string;
+  target_id: string;
+}
+
+export type ParsedAggregateComparison = '!=' | '<' | '<=' | '=' | '>' | '>=';
+export type ParsedAggregateName = 'any' | 'count' | 'none';
+
+export interface ParsedAggregateTerm {
+  aggregate_name: ParsedAggregateName;
+  clauses: ParsedClause[];
+  comparison?: ParsedAggregateComparison;
+  kind: 'aggregate';
+  traversal: ParsedTraversalTerm;
+  value?: number;
+}
+
+export type ParsedTerm =
+  | ParsedAggregateTerm
+  | ParsedFieldSetTerm
+  | ParsedFieldTerm
+  | ParsedRelationTargetTerm
+  | ParsedRelationTerm;
+
+export interface ParsedClause {
+  is_negated: boolean;
+  term: ParsedTerm;
+}
+
+export type ParseWhereClauseResult =
+  | {
+      clauses: ParsedClause[];
+      success: true;
+    }
+  | {
+      diagnostic: PatramDiagnostic;
+      success: false;
+    };

package/lib/patram-cli.js

@@ -1,6 +1,6 @@
 /* eslint-disable max-lines */
 /**
- * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
+ * @import { ParsedCliCommandRequest } from './parse-cli-arguments.types.ts';
  */
 
 import process from 'node:process';
@@ -16,10 +16,17 @@ import { loadPatramConfig } from './load-patram-config.js';
 import { loadProjectGraph } from './load-project-graph.js';
 import { parseCliArguments } from './parse-cli-arguments.js';
 import { DEFAULT_QUERY_LIMIT, queryGraph } from './query-graph.js';
+import { inspectQuery, renderQueryInspection } from './query-inspection.js';
+import { createDerivedSummaryEvaluator } from './derived-summary.js';
 import {
   renderCheckDiagnostics,
   renderCheckSuccess,
 } from './render-check-output.js';
+import {
+  renderCliParseError,
+  renderHelpRequest,
+  renderInvalidWhereDiagnostic,
+} from './render-cli-help.js';
 import {
   resolveCheckTarget,
   selectCheckTargetDiagnostics,
@@ -64,12 +71,20 @@ export async function main(cli_arguments, io_context) {
   const parsed_arguments = parseCliArguments(cli_arguments);
 
   if (!parsed_arguments.success) {
-    io_context.stderr.write(`${parsed_arguments.message}\n`);
+    io_context.stderr.write(renderCliParseError(parsed_arguments.error));
 
     return 1;
   }
 
-  const parsed_command = parsed_arguments.value;
+  if (parsed_arguments.value.kind === 'help') {
+    io_context.stdout.write(renderHelpRequest(parsed_arguments.value));
+
+    return 0;
+  }
+
+  const parsed_command = /** @type {ParsedCliCommandRequest} */ (
+    parsed_arguments.value
+  );
 
   if (parsed_command.command_name === 'check') {
     return runCheckCommand(parsed_command, io_context);
@@ -93,7 +108,7 @@ export async function main(cli_arguments, io_context) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @param {ParsedCliCommandRequest} parsed_command
  * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
  * @returns {Promise<number>}
  */
@@ -147,12 +162,27 @@ async function runCheckCommand(parsed_command, io_context) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @param {ParsedCliCommandRequest} parsed_command
  * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
  * @returns {Promise<number>}
  */
 async function runQueryCommand(parsed_command, io_context) {
   const use_pager = shouldPageCommandOutput(parsed_command, io_context.stdout);
+  const output_mode = resolveOutputMode(parsed_command, {
+    is_tty: io_context.stdout.isTTY === true,
+    no_color: process.env.NO_COLOR !== undefined,
+    term: process.env.TERM,
+  });
+
+  if (parsed_command.query_inspection_mode) {
+    return runQueryInspectionCommand(
+      parsed_command,
+      io_context,
+      output_mode,
+      use_pager,
+    );
+  }
+
   const project_graph_result = await loadProjectGraph(process.cwd());
 
   if (project_graph_result.diagnostics.length > 0) {
@@ -174,31 +204,103 @@ async function runQueryCommand(parsed_command, io_context) {
 
   const query_result = queryGraph(
     project_graph_result.graph,
-    where_clause.value,
+    where_clause.value.where_clause,
     createQueryPaginationOptions(parsed_command, use_pager),
   );
 
   if (query_result.diagnostics.length > 0) {
-    writeDiagnostics(io_context.stderr, query_result.diagnostics);
+    io_context.stderr.write(
+      renderInvalidWhereDiagnostic(query_result.diagnostics[0]),
+    );
 
     return 1;
   }
 
+  const derived_summary_evaluator = createDerivedSummaryEvaluator(
+    project_graph_result.config,
+    project_graph_result.graph,
+  );
+
   await writeCommandOutput(
     io_context,
     parsed_command,
-    createOutputView(
-      'query',
-      query_result.nodes,
-      createQueryOutputOptions(parsed_command, query_result, use_pager),
-    ),
+    createOutputView('query', query_result.nodes, {
+      derived_summary_evaluator,
+      ...createQueryOutputOptions(parsed_command, query_result, use_pager),
+    }),
   );
 
   return 0;
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean } }} io_context
+ * @param {import('./output-view.types.ts').ResolvedOutputMode} output_mode
+ * @param {boolean} use_pager
+ * @returns {Promise<number>}
+ */
+async function runQueryInspectionCommand(
+  parsed_command,
+  io_context,
+  output_mode,
+  use_pager,
+) {
+  const query_inspection_mode = parsed_command.query_inspection_mode;
+
+  if (!query_inspection_mode) {
+    throw new Error('Expected a query inspection mode.');
+  }
+
+  const load_result = await loadPatramConfig(process.cwd());
+
+  if (load_result.diagnostics.length > 0) {
+    io_context.stderr.write(
+      renderCheckDiagnostics(load_result.diagnostics, output_mode),
+    );
+
+    return 1;
+  }
+
+  const repo_config = load_result.config;
+
+  if (!repo_config) {
+    throw new Error('Expected a valid Patram repo config.');
+  }
+
+  const where_clause = resolveWhereClause(
+    repo_config,
+    parsed_command.command_arguments,
+  );
+
+  if (!where_clause.success) {
+    io_context.stderr.write(`${where_clause.message}\n`);
+
+    return 1;
+  }
+
+  const query_inspection = inspectQuery(repo_config, where_clause.value, {
+    inspection_mode: query_inspection_mode,
+    ...createQueryExecutionOptions(parsed_command, use_pager),
+  });
+
+  if (!query_inspection.success) {
+    io_context.stderr.write(
+      renderCheckDiagnostics(query_inspection.diagnostics, output_mode),
+    );
+
+    return 1;
+  }
+
+  io_context.stdout.write(
+    renderQueryInspection(query_inspection.value, output_mode),
+  );
+
+  return 0;
+}
+
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
  * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
  * @returns {Promise<number>}
  */
@@ -227,7 +329,7 @@ async function runQueriesCommand(parsed_command, io_context) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @param {ParsedCliCommandRequest} parsed_command
  * @param {{ stderr: { write(chunk: string): boolean }, stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
  * @returns {Promise<number>}
  */
@@ -252,10 +354,18 @@ async function runShowCommand(parsed_command, io_context) {
     return 1;
   }
 
+  const derived_summary_evaluator = createDerivedSummaryEvaluator(
+    project_graph_result.config,
+    project_graph_result.graph,
+  );
+
   await writeCommandOutput(
     io_context,
     parsed_command,
-    createShowOutputView(show_output.value),
+    createShowOutputView(show_output.value, {
+      derived_summary_evaluator,
+      graph_nodes: project_graph_result.graph.nodes,
+    }),
   );
 
   return 0;
@@ -272,7 +382,7 @@ function writeDiagnostics(output_stream, diagnostics) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @param {ParsedCliCommandRequest} parsed_command
  * @param {{ total_count: number, nodes: import('./build-graph.types.ts').GraphNode[] }} query_result
  * @param {boolean} use_pager
  * @returns {{ hints: string[], limit: number, offset: number, total_count: number }}
@@ -309,7 +419,7 @@ function createQueryOutputOptions(parsed_command, query_result, use_pager) {
 }
 
 /**
- * @param {ParsedCliArguments} parsed_command
+ * @param {ParsedCliCommandRequest} parsed_command
  * @param {boolean} use_pager
  * @returns {{ limit?: number, offset: number }}
  */
@@ -328,6 +438,23 @@ function createQueryPaginationOptions(parsed_command, use_pager) {
   return pagination_options;
 }
 
+/**
+ * @param {ParsedCliCommandRequest} parsed_command
+ * @param {boolean} use_pager
+ * @returns {{ limit: number | null, offset: number }}
+ */
+function createQueryExecutionOptions(parsed_command, use_pager) {
+  const pagination_options = createQueryPaginationOptions(
+    parsed_command,
+    use_pager,
+  );
+
+  return {
+    limit: pagination_options.limit ?? null,
+    offset: pagination_options.offset,
+  };
+}
+
 /**
  * @param {import('./load-patram-config.types.ts').PatramDiagnostic} diagnostic
  * @returns {string}

package/lib/patram.js

@@ -0,0 +1,6 @@
+export {
+  extractTaggedFencedBlocks,
+  loadTaggedFencedBlocks,
+  selectTaggedBlock,
+  selectTaggedBlocks,
+} from './tagged-fenced-blocks.js';