patram 0.9.0 → 0.11.0

package/lib/output/layout-stored-queries.js

@@ -10,7 +10,7 @@ const MIN_TERM_COLUMN_WIDTH = 20;
 const STORED_QUERY_COLUMN_GAP = 2;
 
 /**
- * @typedef {'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain'} StoredQuerySegmentKind
+ * @typedef {'description' | 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain'} StoredQuerySegmentKind
  */
 
 /**
@@ -56,7 +56,8 @@ function layoutStoredQuery(output_item, name_column_width, term_column_width) {
     name_column_width + STORED_QUERY_COLUMN_GAP,
   );
 
-  return term_lines.map((line_segments, line_index) => {
+  /** @type {StoredQuerySegment[][]} */
+  const output_lines = term_lines.map((line_segments, line_index) => {
     if (line_index === 0) {
       return [
         {
@@ -79,6 +80,21 @@ function layoutStoredQuery(output_item, name_column_width, term_column_width) {
       ...line_segments,
     ];
   });
+
+  if (output_item.description) {
+    for (const description_line of output_item.description.split('\n')) {
+      output_lines.push([
+        {
+          kind: 'description',
+          text: `${' '.repeat(name_column_width + STORED_QUERY_COLUMN_GAP)}${description_line}`,
+        },
+      ]);
+    }
+  }
+
+  output_lines.push([]);
+
+  return output_lines;
 }
 
 /**

package/lib/output/list-queries.js

@@ -6,12 +6,13 @@
  * List stored queries in stable name order.
  *
  * @param {Record<string, StoredQueryConfig>} stored_queries
- * @returns {{ name: string, where: string }[]}
+ * @returns {{ name: string, where: string, description?: string }[]}
  */
 export function listQueries(stored_queries) {
   return Object.entries(stored_queries)
     .sort(([left_name], [right_name]) => left_name.localeCompare(right_name))
     .map(([name, stored_query]) => ({
+      description: stored_query.description,
       name,
       where: stored_query.where,
     }));

package/lib/output/renderers/json.js

@@ -92,9 +92,6 @@ function renderJsonRefsOutput(output_view) {
 function renderJsonShowOutput(output_view) {
   return `${JSON.stringify(
     {
-      document: output_view.document
-        ? formatJsonNodeItem(output_view.document)
-        : undefined,
       incoming_summary: output_view.incoming_summary,
       source: output_view.source,
       resolved_links: output_view.items.map(formatJsonResolvedLink),
@@ -144,13 +141,20 @@ function formatJsonNodeItem(output_item) {
 
 /**
  * @param {OutputStoredQueryItem} output_item
- * @returns {{ name: string, where: string }}
+ * @returns {{ name: string, where: string, description?: string }}
  */
 function formatJsonStoredQuery(output_item) {
-  return {
+  /** @type {{ description?: string, name: string, where: string }} */
+  const stored_query = {
     name: output_item.name,
     where: output_item.where,
   };
+
+  if (output_item.description) {
+    stored_query.description = output_item.description;
+  }
+
+  return stored_query;
 }
 
 /**

package/lib/output/renderers/plain.js

@@ -24,7 +24,7 @@ export function renderPlainOutput(output_view) {
   }
 
   if (output_view.command === 'queries') {
-    return renderPlainStoredQueries(output_view.items);
+    return renderPlainStoredQueries(output_view);
   }
 
   if (output_view.command === 'refs') {
@@ -69,17 +69,23 @@ function renderPlainEmptyQuery(footer) {
 }
 
 /**
- * @param {OutputStoredQueryItem[]} output_items
+ * @param {Extract<OutputView, { command: 'queries' }>} output_view
  * @returns {string}
  */
-function renderPlainStoredQueries(output_items) {
-  if (output_items.length === 0) {
+function renderPlainStoredQueries(output_view) {
+  if (output_view.items.length === 0) {
     return '';
   }
 
-  return `${layoutStoredQueries(output_items)
-    .map(formatPlainStoredQueryLine)
-    .join('\n')}\n`;
+  const output_lines = layoutStoredQueries(output_view.items).map(
+    formatPlainStoredQueryLine,
+  );
+
+  if (output_view.hints.length === 0) {
+    return `${output_lines.join('\n')}\n`;
+  }
+
+  return `${output_lines.join('\n')}\n${output_view.hints.join('\n')}\n`;
 }
 
 /**
@@ -88,29 +94,12 @@ function renderPlainStoredQueries(output_items) {
  */
 function renderPlainShowOutput(output_view) {
   const rendered_source = trimTrailingLineBreaks(output_view.rendered_source);
-  const document_summary = output_view.document
-    ? formatPlainNodeItem(output_view.document)
-    : '';
   const incoming_summary = renderPlainIncomingSummary(output_view);
 
-  if (
-    document_summary.length === 0 &&
-    output_view.items.length === 0 &&
-    incoming_summary.length === 0
-  ) {
+  if (output_view.items.length === 0 && incoming_summary.length === 0) {
     return `${rendered_source}\n`;
   }
-
-  /** @type {string[]} */
-  const summary_items = [];
-
-  if (document_summary.length > 0) {
-    summary_items.push(document_summary);
-  }
-
-  summary_items.push(...output_view.items.map(formatPlainResolvedLinkItem));
-
-  const summary_blocks = summary_items.filter((summary_item) => summary_item);
+  const summary_blocks = output_view.items.map(formatPlainResolvedLinkItem);
 
   if (incoming_summary.length > 0) {
     summary_blocks.push(incoming_summary);

package/lib/output/renderers/rich.js

@@ -33,7 +33,7 @@ export async function renderRichOutput(output_view, render_options) {
   }
 
   if (output_view.command === 'queries') {
-    return renderRichStoredQueries(output_view.items, ansi);
+    return renderRichStoredQueries(output_view, ansi);
   }
 
   if (output_view.command === 'refs') {
@@ -83,18 +83,24 @@ function renderRichEmptyQuery(footer, ansi) {
 }
 
 /**
- * @param {OutputStoredQueryItem[]} output_items
+ * @param {Extract<OutputView, { command: 'queries' }>} output_view
  * @param {Ansis} ansi
  * @returns {string}
  */
-function renderRichStoredQueries(output_items, ansi) {
-  if (output_items.length === 0) {
+function renderRichStoredQueries(output_view, ansi) {
+  if (output_view.items.length === 0) {
     return '';
   }
 
-  return `${layoutStoredQueries(output_items)
-    .map((line_segments) => formatRichStoredQueryLine(line_segments, ansi))
-    .join('\n')}\n`;
+  const output_lines = layoutStoredQueries(output_view.items).map(
+    (line_segments) => formatRichStoredQueryLine(line_segments, ansi),
+  );
+
+  if (output_view.hints.length === 0) {
+    return `${output_lines.join('\n')}\n`;
+  }
+
+  return `${output_lines.join('\n')}\n${output_view.hints.map((hint) => ansi.gray(hint)).join('\n')}\n`;
 }
 
 /**
@@ -107,28 +113,14 @@ async function renderRichShowOutput(output_view, render_options, ansi) {
   const rendered_source = trimTrailingLineBreaks(
     await renderRichSource(output_view, render_options),
   );
-  const document_summary = output_view.document
-    ? formatRichNodeItem(output_view.document, ansi)
-    : '';
   const incoming_summary = renderRichIncomingSummary(output_view, ansi);
 
-  if (
-    document_summary.length === 0 &&
-    output_view.items.length === 0 &&
-    incoming_summary.length === 0
-  ) {
+  if (output_view.items.length === 0 && incoming_summary.length === 0) {
     return `${rendered_source}\n`;
   }
 
-  /** @type {string[]} */
-  const summary_items = [];
-
-  if (document_summary.length > 0) {
-    summary_items.push(document_summary);
-  }
-
-  summary_items.push(
-    ...output_view.items.map((item) => formatRichResolvedLinkItem(item, ansi)),
+  const summary_items = output_view.items.map((item) =>
+    formatRichResolvedLinkItem(item, ansi),
   );
 
   if (incoming_summary.length > 0) {
@@ -173,7 +165,7 @@ function formatRichNodeItem(output_item, ansi) {
 }
 
 /**
- * @param {{ kind: 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }[]} line_segments
+ * @param {{ kind: 'description' | 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }[]} line_segments
  * @param {Ansis} ansi
  * @returns {string}
  */
@@ -232,7 +224,7 @@ function createAnsi(color_enabled) {
 }
 
 /**
- * @param {{ kind: 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }} line_segment
+ * @param {{ kind: 'description' | 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }} line_segment
  * @param {Ansis} ansi
  * @returns {string}
  */
@@ -241,6 +233,10 @@ function styleStoredQuerySegment(line_segment, ansi) {
     return ansi.green(line_segment.text);
   }
 
+  if (line_segment.kind === 'description') {
+    return ansi.gray(line_segment.text);
+  }
+
   if (line_segment.kind === 'operator') {
     return ansi.gray(line_segment.text);
   }

package/lib/output/resolve-check-target.js

@@ -21,7 +21,7 @@ const CONFIG_FILE_NAME = '.patram.json';
  * @param {string | undefined} target_argument
  * @returns {Promise<ResolvedCheckTarget>}
  */
-export async function resolveCheckTarget(target_argument) {
+async function resolveCheckTarget(target_argument) {
   if (target_argument === undefined) {
     return {
       project_directory: process.cwd(),
@@ -35,23 +35,19 @@ export async function resolveCheckTarget(target_argument) {
     ? absolute_target_path
     : dirname(absolute_target_path);
   const project_directory = await findProjectDirectory(target_directory);
-
   if (target_stats.isFile()) {
     const target_path = normalizeRepoRelativePath(
       relative(project_directory, absolute_target_path),
     );
-
     return {
       project_directory,
       target_kind: 'file',
       target_path,
     };
   }
-
   const target_path = normalizeRepoRelativePath(
     relative(project_directory, absolute_target_path),
   );
-
   if (target_path.length === 0) {
     return {
       project_directory,
@@ -65,7 +61,36 @@ export async function resolveCheckTarget(target_argument) {
     target_path,
   };
 }
+/**
+ * @param {string[]} target_arguments
+ * @returns {Promise<ResolvedCheckTarget[]>}
+ */
+export async function resolveCheckTargets(target_arguments) {
+  if (target_arguments.length === 0) {
+    return [await resolveCheckTarget(undefined)];
+  }
 
+  return Promise.all(
+    target_arguments.map((target_argument) =>
+      resolveCheckTarget(target_argument),
+    ),
+  );
+}
+/** @param {ResolvedCheckTarget[]} resolved_targets
+ * @returns {string | null}
+ */
+export function resolveCheckTargetProjectDirectory(resolved_targets) {
+  const project_directory = resolved_targets[0]?.project_directory;
+  if (!project_directory) {
+    return null;
+  }
+  for (const resolved_target of resolved_targets) {
+    if (resolved_target.project_directory !== project_directory) {
+      return null;
+    }
+  }
+  return project_directory;
+}
 /**
  * Select the source files covered by one resolved `check` target.
  *
@@ -73,10 +98,7 @@ export async function resolveCheckTarget(target_argument) {
  * @param {ResolvedCheckTarget} resolved_target
  * @returns {string[]}
  */
-export function selectCheckTargetSourceFiles(
-  source_file_paths,
-  resolved_target,
-) {
+function selectCheckTargetSourceFiles(source_file_paths, resolved_target) {
   if (resolved_target.target_kind === 'project') {
     return source_file_paths;
   }
@@ -91,7 +113,22 @@ export function selectCheckTargetSourceFiles(
     isPathInsideDirectory(source_file_path, resolved_target.target_path),
   );
 }
-
+/**
+ * @param {string[]} source_file_paths
+ * @param {ResolvedCheckTarget[]} resolved_targets
+ * @returns {string[]}
+ */
+export function selectCheckTargetsSourceFiles(
+  source_file_paths,
+  resolved_targets,
+) {
+  return selectCheckTargetValues(
+    source_file_paths,
+    resolved_targets,
+    selectCheckTargetSourceFiles,
+    (source_file_path) => source_file_path,
+  );
+}
 /**
  * Filter diagnostics to one resolved `check` target.
  *
@@ -99,7 +136,7 @@ export function selectCheckTargetSourceFiles(
  * @param {ResolvedCheckTarget} resolved_target
  * @returns {PatramDiagnostic[]}
  */
-export function selectCheckTargetDiagnostics(diagnostics, resolved_target) {
+function selectCheckTargetDiagnostics(diagnostics, resolved_target) {
   if (resolved_target.target_kind === 'project') {
     return diagnostics;
   }
@@ -115,6 +152,20 @@ export function selectCheckTargetDiagnostics(diagnostics, resolved_target) {
   );
 }
 
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {ResolvedCheckTarget[]} resolved_targets
+ * @returns {PatramDiagnostic[]}
+ */
+export function selectCheckTargetsDiagnostics(diagnostics, resolved_targets) {
+  return selectCheckTargetValues(
+    diagnostics,
+    resolved_targets,
+    selectCheckTargetDiagnostics,
+    createDiagnosticKey,
+  );
+}
+
 /**
  * @param {string} start_directory
  * @returns {Promise<string>}
@@ -155,6 +206,49 @@ async function hasConfigFile(directory_path) {
   return true;
 }
 
+/**
+ * @template ValueType
+ * @param {ValueType[]} values
+ * @param {ResolvedCheckTarget[]} resolved_targets
+ * @param {(values: ValueType[], resolved_target: ResolvedCheckTarget) => ValueType[]} select_values
+ * @param {(value: ValueType) => string} get_value_key
+ * @returns {ValueType[]}
+ */
+function selectCheckTargetValues(
+  values,
+  resolved_targets,
+  select_values,
+  get_value_key,
+) {
+  if (
+    resolved_targets.some(
+      (resolved_target) => resolved_target.target_kind === 'project',
+    )
+  ) {
+    return values;
+  }
+
+  /** @type {Set<string>} */
+  const selected_keys = new Set();
+  /** @type {ValueType[]} */
+  const selected_values = [];
+
+  for (const resolved_target of resolved_targets) {
+    for (const value of select_values(values, resolved_target)) {
+      const value_key = get_value_key(value);
+
+      if (selected_keys.has(value_key)) {
+        continue;
+      }
+
+      selected_keys.add(value_key);
+      selected_values.push(value);
+    }
+  }
+
+  return selected_values;
+}
+
 /**
  * @param {string} source_path
  * @param {string} directory_path
@@ -175,6 +269,21 @@ function normalizeRepoRelativePath(source_path) {
   return source_path.replaceAll('\\', '/');
 }
 
+/**
+ * @param {PatramDiagnostic} diagnostic
+ * @returns {string}
+ */
+function createDiagnosticKey(diagnostic) {
+  return [
+    diagnostic.path,
+    diagnostic.line,
+    diagnostic.column,
+    diagnostic.level,
+    diagnostic.code,
+    diagnostic.message,
+  ].join(':');
+}
+
 /**
  * @param {unknown} error
  * @returns {error is NodeJS.ErrnoException}

package/lib/output/view-model/index.js

@@ -12,7 +12,7 @@ import { resolveDocumentNodeId } from '../../graph/build-graph-identity.js';
  * Create a shared output view from one command result.
  *
  * @param {'query' | 'queries'} command_name
- * @param {GraphNode[] | { name: string, where: string }[]} command_items
+ * @param {GraphNode[] | { name: string, where: string, description?: string }[]} command_items
  * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, hints?: string[], limit?: number, offset?: number, repo_config?: PatramRepoConfig, total_count?: number }=} command_options
  * @returns {OutputView}
  */
@@ -41,23 +41,8 @@ export function createOutputView(command_name, command_items, command_options) {
  * @returns {ShowOutputView}
  */
 export function createShowOutputView(show_output, command_options = {}) {
-  const shown_document_node = resolveDocumentGraphNode(
-    command_options.graph_nodes,
-    command_options.document_node_ids,
-    show_output.path,
-  );
-
   return {
     command: 'show',
-    document: shown_document_node
-      ? createOutputNodeItem(
-          shown_document_node,
-          command_options.derived_summary_evaluator?.evaluate(
-            shown_document_node,
-          ) ?? null,
-          command_options.repo_config?.fields ?? {},
-        )
-      : undefined,
     hints: [],
     incoming_summary: show_output.incoming_summary,
     items: show_output.resolved_links.map((resolved_link) =>
@@ -144,17 +129,19 @@ function createQueryOutputView(graph_nodes, command_options = {}) {
 }
 
 /**
- * @param {{ name: string, where: string }[]} stored_queries
+ * @param {{ name: string, where: string, description?: string }[]} stored_queries
  * @returns {OutputView}
  */
 function createStoredQueriesOutputView(stored_queries) {
   return {
     command: 'queries',
-    hints: [],
+    hints:
+      stored_queries.length === 0 ? [] : ['Hint: patram help query-language'],
     items: stored_queries.map((stored_query) => ({
       kind: 'stored_query',
       name: stored_query.name,
       where: stored_query.where,
+      description: stored_query.description,
     })),
     summary: {
       count: stored_queries.length,

package/lib/patram.d.ts

@@ -48,6 +48,8 @@ export type PatramParsedTerm =
   import('./graph/parse-where-clause.types.d.ts').ParsedTerm;
 export type PatramParsedExpression =
   import('./graph/parse-where-clause.types.d.ts').ParsedExpression;
+export type PatramParseResult =
+  import('./graph/parse-where-clause.types.d.ts').ParseWhereClauseResult;
 export type PatramParseWhereClauseResult =
   import('./graph/parse-where-clause.types.d.ts').ParseWhereClauseResult;
 export type PatramQuerySource =
@@ -59,6 +61,12 @@ export type PatramQuerySource =
       name: string;
     };
 
+export interface PatramQueryGraphOptions {
+  bindings?: Record<string, string>;
+  limit?: number;
+  offset?: number;
+}
+
 export interface PatramProjectGraphResult {
   claims: import('./parse/parse-claims.types.d.ts').PatramClaim[];
   config: import('./config/load-patram-config.types.d.ts').PatramRepoConfig;