patram 0.6.2 → 0.8.0

package/lib/patram.d.ts

@@ -0,0 +1,73 @@
+export {
+  extractTaggedFencedBlocks,
+  loadTaggedFencedBlocks,
+  selectTaggedBlock,
+  selectTaggedBlocks,
+} from './tagged-fenced-blocks.js';
+
+export { parseWhereClause } from './parse-where-clause.js';
+export { getQuerySemanticDiagnostics } from './query-inspection.js';
+export { loadProjectGraph } from './load-project-graph.js';
+export { overlayGraph } from './overlay-graph.js';
+export { queryGraph } from './query-graph.js';
+
+export type PatramGraphNode = import('./build-graph.types.ts').GraphNode;
+export type PatramGraphEdge = import('./build-graph.types.ts').GraphEdge;
+export type PatramBuildGraphResult =
+  import('./build-graph.types.ts').BuildGraphResult;
+export type PatramDiagnostic =
+  import('./load-patram-config.types.ts').PatramDiagnostic;
+export type PatramRepoConfig =
+  import('./load-patram-config.types.ts').PatramRepoConfig;
+export type PatramParsedFieldName =
+  import('./parse-where-clause.types.ts').ParsedFieldName;
+export type PatramParsedFieldTerm =
+  import('./parse-where-clause.types.ts').ParsedFieldTerm;
+export type PatramParsedFieldSetTerm =
+  import('./parse-where-clause.types.ts').ParsedFieldSetTerm;
+export type PatramParsedTraversalTerm =
+  import('./parse-where-clause.types.ts').ParsedTraversalTerm;
+export type PatramParsedRelationTerm =
+  import('./parse-where-clause.types.ts').ParsedRelationTerm;
+export type PatramParsedRelationTargetTerm =
+  import('./parse-where-clause.types.ts').ParsedRelationTargetTerm;
+export type PatramParsedAggregateComparison =
+  import('./parse-where-clause.types.ts').ParsedAggregateComparison;
+export type PatramParsedAggregateName =
+  import('./parse-where-clause.types.ts').ParsedAggregateName;
+export type PatramParsedAggregateTerm =
+  import('./parse-where-clause.types.ts').ParsedAggregateTerm;
+export type PatramParsedTermExpression =
+  import('./parse-where-clause.types.ts').ParsedTermExpression;
+export type PatramParsedNotExpression =
+  import('./parse-where-clause.types.ts').ParsedNotExpression;
+export type PatramParsedBooleanExpression =
+  import('./parse-where-clause.types.ts').ParsedBooleanExpression;
+export type PatramParsedTerm =
+  import('./parse-where-clause.types.ts').ParsedTerm;
+export type PatramParsedExpression =
+  import('./parse-where-clause.types.ts').ParsedExpression;
+export type PatramParseWhereClauseResult =
+  import('./parse-where-clause.types.ts').ParseWhereClauseResult;
+export type PatramQuerySource =
+  | {
+      kind: 'ad_hoc';
+    }
+  | {
+      kind: 'stored_query';
+      name: string;
+    };
+
+export interface PatramProjectGraphResult {
+  claims: import('./parse-claims.types.ts').PatramClaim[];
+  config: import('./load-patram-config.types.ts').PatramRepoConfig;
+  diagnostics: PatramDiagnostic[];
+  graph: PatramBuildGraphResult;
+  source_file_paths: string[];
+}
+
+export interface PatramQueryResult {
+  diagnostics: PatramDiagnostic[];
+  nodes: PatramGraphNode[];
+  total_count: number;
+}

package/lib/patram.js

@@ -5,5 +5,8 @@ export {
   selectTaggedBlocks,
 } from './tagged-fenced-blocks.js';
 
+export { parseWhereClause } from './parse-where-clause.js';
+export { getQuerySemanticDiagnostics } from './query-inspection.js';
 export { loadProjectGraph } from './load-project-graph.js';
+export { overlayGraph } from './overlay-graph.js';
 export { queryGraph } from './query-graph.js';

package/lib/query-graph.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @typedef {{
+ *   incoming: Map<string, Map<string, Set<string>>>,
+ *   outgoing: Map<string, Map<string, Set<string>>>,
+ * }} RelationIndexes
+ */
+/**
+ * @typedef {{
+ *   bindings?: Record<string, string>,
+ *   limit?: number,
+ *   offset?: number,
+ * }} QueryGraphOptions
+ */
+/**
+ * @typedef {{
+ *   nodes: BuildGraphResult['nodes'],
+ *   relation_indexes: RelationIndexes,
+ * }} EvaluationContext
+ */
+/**
+ * Filter graph nodes with the query language.
+ *
+ * @param {BuildGraphResult} graph
+ * @param {string} where_clause
+ * @param {PatramRepoConfig | QueryGraphOptions=} repo_config_or_query_options
+ * @param {QueryGraphOptions=} query_options
+ * @returns {{ diagnostics: PatramDiagnostic[], nodes: GraphNode[], total_count: number }}
+ */
+export function queryGraph(graph: BuildGraphResult, where_clause: string, repo_config_or_query_options?: (PatramRepoConfig | QueryGraphOptions) | undefined, query_options?: QueryGraphOptions | undefined): {
+    diagnostics: PatramDiagnostic[];
+    nodes: GraphNode[];
+    total_count: number;
+};
+/**
+ * Query graph filtering.
+ *
+ * Applies the v0 where-clause language to graph nodes and keeps pagination
+ * separate from matching.
+ *
+ * Kind: graph
+ * Status: active
+ * Uses Term: ../docs/reference/terms/graph.md
+ * Uses Term: ../docs/reference/terms/query.md
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/query-language.md
+ * Implements: ../docs/tasks/v0/query-command.md
+ * @patram
+ * @see {@link ./load-project-graph.js}
+ * @see {@link ../docs/decisions/query-language.md}
+ */
+export const DEFAULT_QUERY_LIMIT: 25;
+export type RelationIndexes = {
+    incoming: Map<string, Map<string, Set<string>>>;
+    outgoing: Map<string, Map<string, Set<string>>>;
+};
+export type QueryGraphOptions = {
+    bindings?: Record<string, string>;
+    limit?: number;
+    offset?: number;
+};
+export type EvaluationContext = {
+    nodes: BuildGraphResult["nodes"];
+    relation_indexes: RelationIndexes;
+};
+import type { BuildGraphResult } from './build-graph.types.ts';
+import type { PatramRepoConfig } from './load-patram-config.types.ts';
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { GraphNode } from './build-graph.types.ts';

package/lib/query-graph.js

@@ -43,6 +43,14 @@ export const DEFAULT_QUERY_LIMIT = 25;
  * }} RelationIndexes
  */
 
+/**
+ * @typedef {{
+ *   bindings?: Record<string, string>,
+ *   limit?: number,
+ *   offset?: number,
+ * }} QueryGraphOptions
+ */
+
 /**
  * @typedef {{
  *   nodes: BuildGraphResult['nodes'],
@@ -55,17 +63,21 @@ export const DEFAULT_QUERY_LIMIT = 25;
  *
  * @param {BuildGraphResult} graph
  * @param {string} where_clause
- * @param {PatramRepoConfig | { limit?: number, offset?: number }=} repo_config_or_pagination
- * @param {{ limit?: number, offset?: number }=} pagination_options
+ * @param {PatramRepoConfig | QueryGraphOptions=} repo_config_or_query_options
+ * @param {QueryGraphOptions=} query_options
  * @returns {{ diagnostics: PatramDiagnostic[], nodes: GraphNode[], total_count: number }}
  */
 export function queryGraph(
   graph,
   where_clause,
-  repo_config_or_pagination = {},
-  pagination_options = {},
+  repo_config_or_query_options = {},
+  query_options = {},
 ) {
-  const parse_result = parseWhereClause(where_clause);
+  const { query_options: resolved_query_options, repo_config } =
+    resolveQueryGraphOptions(repo_config_or_query_options, query_options);
+  const parse_result = parseWhereClause(where_clause, {
+    bindings: resolved_query_options.bindings,
+  });
 
   if (!parse_result.success) {
     return {
@@ -75,9 +87,6 @@ export function queryGraph(
     };
   }
 
-  const { pagination_options: resolved_pagination_options, repo_config } =
-    resolveQueryGraphOptions(repo_config_or_pagination, pagination_options);
-
   if (repo_config) {
     const diagnostics = getQuerySemanticDiagnostics(
       repo_config,
@@ -102,10 +111,7 @@ export function queryGraph(
   const matching_nodes = graph_nodes.filter((graph_node) =>
     matchesExpression(graph_node, parse_result.expression, evaluation_context),
   );
-  const paginated_nodes = paginateNodes(
-    matching_nodes,
-    resolved_pagination_options,
-  );
+  const paginated_nodes = paginateNodes(matching_nodes, resolved_query_options);
 
   return {
     diagnostics: [],
@@ -501,29 +507,26 @@ function getScalarFieldValue(field_value) {
 }
 
 /**
- * @param {PatramRepoConfig | { limit?: number, offset?: number }} repo_config_or_pagination
- * @param {{ limit?: number, offset?: number }} pagination_options
- * @returns {{ pagination_options: { limit?: number, offset?: number }, repo_config: PatramRepoConfig | null }}
+ * @param {PatramRepoConfig | QueryGraphOptions} repo_config_or_query_options
+ * @param {QueryGraphOptions} query_options
+ * @returns {{ query_options: QueryGraphOptions, repo_config: PatramRepoConfig | null }}
  */
-function resolveQueryGraphOptions(
-  repo_config_or_pagination,
-  pagination_options,
-) {
-  if (isRepoConfig(repo_config_or_pagination)) {
+function resolveQueryGraphOptions(repo_config_or_query_options, query_options) {
+  if (isRepoConfig(repo_config_or_query_options)) {
     return {
-      pagination_options,
-      repo_config: repo_config_or_pagination,
+      query_options,
+      repo_config: repo_config_or_query_options,
     };
   }
 
   return {
-    pagination_options: repo_config_or_pagination,
+    query_options: repo_config_or_query_options,
     repo_config: null,
   };
 }
 
 /**
- * @param {PatramRepoConfig | { limit?: number, offset?: number }} value
+ * @param {PatramRepoConfig | QueryGraphOptions} value
  * @returns {value is PatramRepoConfig}
  */
 function isRepoConfig(value) {

package/lib/query-inspection.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @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
+ */
+/**
+ * @typedef {{ inspection_mode: 'explain' | 'lint', limit: number | null, offset: number }} QueryInspectionOptions
+ */
+/**
+ * @typedef {{
+ *   execution?: {
+ *     limit: number | null,
+ *     offset: number,
+ *   },
+ *   expression?: ParsedExpression,
+ *   inspection_mode: 'explain' | 'lint',
+ *   query_source: QuerySource,
+ *   where_clause: string,
+ * }} QueryInspectionSuccess
+ */
+/**
+ * Inspect one resolved query without executing it.
+ *
+ * @param {PatramRepoConfig} repo_config
+ * @param {ResolvedWhereClause} resolved_where_clause
+ * @param {QueryInspectionOptions} inspection_options
+ * @returns {{ success: true, value: QueryInspectionSuccess } | { diagnostics: PatramDiagnostic[], success: false }}
+ */
+export function inspectQuery(repo_config: PatramRepoConfig, resolved_where_clause: ResolvedWhereClause, inspection_options: QueryInspectionOptions): {
+    success: true;
+    value: QueryInspectionSuccess;
+} | {
+    diagnostics: PatramDiagnostic[];
+    success: false;
+};
+/**
+ * Render a successful query inspection in one output mode.
+ *
+ * @param {QueryInspectionSuccess} query_inspection
+ * @param {ResolvedOutputMode} output_mode
+ * @returns {string}
+ */
+export function renderQueryInspection(query_inspection: QueryInspectionSuccess, output_mode: ResolvedOutputMode): string;
+/**
+ * Collect schema-aware diagnostics for one parsed where clause.
+ *
+ * @param {PatramRepoConfig} repo_config
+ * @param {QuerySource} query_source
+ * @param {ParsedExpression} expression
+ * @returns {PatramDiagnostic[]}
+ */
+export function getQuerySemanticDiagnostics(repo_config: PatramRepoConfig, query_source: QuerySource, expression: ParsedExpression): PatramDiagnostic[];
+export type QuerySource = {
+    kind: "ad_hoc";
+} | {
+    kind: "stored_query";
+    name: string;
+};
+export type FieldDiagnosticTerm = import("./parse-where-clause.types.ts").ParsedFieldTerm | import("./parse-where-clause.types.ts").ParsedFieldSetTerm;
+export type ResolvedWhereClause = {
+    query_source: QuerySource;
+    where_clause: string;
+};
+export type QueryInspectionOptions = {
+    inspection_mode: "explain" | "lint";
+    limit: number | null;
+    offset: number;
+};
+export type QueryInspectionSuccess = {
+    execution?: {
+        limit: number | null;
+        offset: number;
+    };
+    expression?: ParsedExpression;
+    inspection_mode: "explain" | "lint";
+    query_source: QuerySource;
+    where_clause: string;
+};
+import type { PatramRepoConfig } from './load-patram-config.types.ts';
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { ResolvedOutputMode } from './output-view.types.ts';
+import type { ParsedExpression } from './parse-where-clause.types.ts';

package/lib/render-cli-help.js

@@ -308,7 +308,7 @@ function renderInvalidCommandOptionError(command_name, invalid_token) {
 }
 
 /**
- * @param {'query' | 'show'} command_name
+ * @param {'query' | 'refs' | 'show'} command_name
  * @param {string} argument_label
  * @returns {string}
  */

package/lib/render-json-output.js

@@ -10,54 +10,113 @@
  */
 export function renderJsonOutput(output_view) {
   if (output_view.command === 'query') {
-    return `${JSON.stringify(
-      {
-        results: output_view.items.map(formatJsonQueryItem),
-        summary: {
-          shown_count: output_view.summary.count,
-          total_count: output_view.summary.total_count,
-          offset: output_view.summary.offset,
-          limit: output_view.summary.limit,
-        },
-        hints: output_view.hints,
-      },
-      null,
-      2,
-    )}\n`;
+    return renderJsonQueryOutput(output_view);
   }
 
   if (output_view.command === 'queries') {
-    return `${JSON.stringify(
-      {
-        queries: output_view.items.map(formatJsonStoredQuery),
-      },
-      null,
-      2,
-    )}\n`;
+    return renderJsonQueriesOutput(output_view.items);
+  }
+
+  if (output_view.command === 'refs') {
+    return renderJsonRefsOutput(output_view);
   }
 
   if (output_view.command === 'show') {
-    return `${JSON.stringify(
-      {
-        document: output_view.document
-          ? formatJsonShowDocument(output_view.document)
-          : undefined,
-        source: output_view.source,
-        resolved_links: output_view.items.map(formatJsonResolvedLink),
-      },
-      null,
-      2,
-    )}\n`;
+    return renderJsonShowOutput(output_view);
   }
 
   throw new Error('Unsupported output view command.');
 }
 
+/**
+ * @param {Extract<OutputView, { command: 'query' }>} output_view
+ * @returns {string}
+ */
+function renderJsonQueryOutput(output_view) {
+  return `${JSON.stringify(
+    {
+      results: output_view.items.map(formatJsonQueryItem),
+      summary: {
+        shown_count: output_view.summary.count,
+        total_count: output_view.summary.total_count,
+        offset: output_view.summary.offset,
+        limit: output_view.summary.limit,
+      },
+      hints: output_view.hints,
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * @param {OutputStoredQueryItem[]} output_items
+ * @returns {string}
+ */
+function renderJsonQueriesOutput(output_items) {
+  return `${JSON.stringify(
+    {
+      queries: output_items.map(formatJsonStoredQuery),
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * @param {Extract<OutputView, { command: 'refs' }>} output_view
+ * @returns {string}
+ */
+function renderJsonRefsOutput(output_view) {
+  return `${JSON.stringify(
+    {
+      node: formatJsonNodeItem(output_view.node),
+      incoming: Object.fromEntries(
+        Object.entries(output_view.incoming).map(
+          ([relation_name, output_items]) => [
+            relation_name,
+            output_items.map(formatJsonNodeItem),
+          ],
+        ),
+      ),
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+/**
+ * @param {Extract<OutputView, { command: 'show' }>} output_view
+ * @returns {string}
+ */
+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),
+    },
+    null,
+    2,
+  )}\n`;
+}
+
 /**
  * @param {OutputNodeItem} output_item
  * @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) {
+  return formatJsonNodeItem(output_item);
+}
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @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 formatJsonNodeItem(output_item) {
   /** @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 = {
     $class: output_item.node_kind,
@@ -128,33 +187,3 @@ function formatJsonResolvedLink(output_item) {
 
   return resolved_link;
 }
-
-/**
- * @param {OutputNodeItem} output_item
- * @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 {{ '$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 = {
-    $class: output_item.node_kind,
-    $id: output_item.id,
-    fields: output_item.fields,
-    title: output_item.title,
-  };
-
-  if (output_item.path) {
-    document_summary.$path = output_item.path;
-  }
-
-  if (output_item.derived_summary) {
-    document_summary.derived_summary = output_item.derived_summary.name;
-    document_summary.derived = Object.fromEntries(
-      output_item.derived_summary.fields.map((field) => [
-        field.name,
-        field.value,
-      ]),
-    );
-  }
-
-  return document_summary;
-}

package/lib/render-output-view.js

@@ -3,7 +3,7 @@
  * @import { DerivedSummaryEvaluator } from './derived-summary.js';
  * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
- * @import { OutputDerivedSummary, OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
+ * @import { OutputDerivedSummary, OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, RefsOutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
  */
 /* eslint-disable max-lines */
 
@@ -55,7 +55,7 @@ export function createOutputView(command_name, command_items, command_options) {
 /**
  * Create a shared output view for the show command.
  *
- * @param {{ path: string, rendered_source: string, resolved_links: Array<{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }>, source: string }} show_output
+ * @param {{ incoming_summary: Record<string, number>, path: string, rendered_source: string, resolved_links: Array<{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }>, source: string }} show_output
  * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, document_node_ids?: BuildGraphResult['document_node_ids'], graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }=} command_options
  * @returns {ShowOutputView}
  */
@@ -78,6 +78,7 @@ export function createShowOutputView(show_output, command_options = {}) {
         )
       : undefined,
     hints: [],
+    incoming_summary: show_output.incoming_summary,
     items: show_output.resolved_links.map((resolved_link) =>
       createResolvedLinkOutputItem(resolved_link, command_options),
     ),
@@ -91,6 +92,46 @@ export function createShowOutputView(show_output, command_options = {}) {
   };
 }
 
+/**
+ * Create a shared output view for the refs command.
+ *
+ * @param {{ incoming: Record<string, GraphNode[]>, node: GraphNode }} refs_output
+ * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, repo_config?: PatramRepoConfig }=} command_options
+ * @returns {RefsOutputView}
+ */
+export function createRefsOutputView(refs_output, command_options = {}) {
+  /** @type {Record<string, OutputNodeItem[]>} */
+  const incoming = {};
+
+  for (const relation_name of Object.keys(refs_output.incoming)) {
+    incoming[relation_name] = refs_output.incoming[relation_name].map(
+      (graph_node) =>
+        createOutputNodeItem(
+          graph_node,
+          command_options.derived_summary_evaluator?.evaluate(graph_node) ??
+            null,
+          command_options.repo_config?.fields ?? {},
+        ),
+    );
+  }
+
+  return {
+    command: 'refs',
+    hints: [],
+    incoming,
+    node: createOutputNodeItem(
+      refs_output.node,
+      command_options.derived_summary_evaluator?.evaluate(refs_output.node) ??
+        null,
+      command_options.repo_config?.fields ?? {},
+    ),
+    summary: {
+      count: countIncomingReferenceItems(incoming),
+      kind: 'incoming_reference_list',
+    },
+  };
+}
+
 /**
  * Render one shared output view through the resolved renderer.
  *
@@ -130,7 +171,7 @@ function createQueryOutputView(graph_nodes, command_options = {}) {
     command: 'query',
     hints:
       command_options.hints ??
-      (total_count === 0 ? ['Try: patram query --where "$class=task"'] : []),
+      (total_count === 0 ? ["Try: patram query --where '$class=task'"] : []),
     items: graph_nodes.map((graph_node) =>
       createOutputNodeItem(
         graph_node,
@@ -168,6 +209,20 @@ function createStoredQueriesOutputView(stored_queries) {
   };
 }
 
+/**
+ * @param {Record<string, OutputNodeItem[]>} incoming
+ * @returns {number}
+ */
+function countIncomingReferenceItems(incoming) {
+  let count = 0;
+
+  for (const output_items of Object.values(incoming)) {
+    count += output_items.length;
+  }
+
+  return count;
+}
+
 /**
  * @param {GraphNode} graph_node
  * @param {OutputDerivedSummary | null} derived_summary