patram 0.8.0 → 0.10.0

package/lib/{query-graph.d.ts → graph/query/execute.d.ts}

@@ -39,14 +39,14 @@ export function queryGraph(graph: BuildGraphResult, where_clause: string, repo_c
  *
  * 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
+ * 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}
+ * @see {@link ../../../docs/decisions/query-language.md}
+ * @see {@link ../load-project-graph.js}
  */
 export const DEFAULT_QUERY_LIMIT: 25;
 export type RelationIndexes = {
@@ -62,7 +62,7 @@ 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';
+import type { BuildGraphResult } from '../build-graph.types.d.ts';
+import type { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
+import type { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';
+import type { GraphNode } from '../build-graph.types.d.ts';

package/lib/{query-graph.js → graph/query/execute.js}

@@ -1,7 +1,7 @@
 /* eslint-disable max-lines */
 /**
- * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
- * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { BuildGraphResult, GraphNode } from '../build-graph.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from '../../config/load-patram-config.types.ts';
  * @import {
  *   ParsedAggregateTerm,
  *   ParsedExpression,
@@ -10,11 +10,11 @@
  *   ParsedRelationTargetTerm,
  *   ParsedTerm,
  *   ParsedTraversalTerm,
- * } from './parse-where-clause.types.ts';
+ * } from '../parse-where-clause.types.ts';
  */
 
-import { parseWhereClause } from './parse-where-clause.js';
-import { getQuerySemanticDiagnostics } from './query-inspection.js';
+import { parseWhereClause } from './parse.js';
+import { getQuerySemanticDiagnostics } from './inspect.js';
 
 /**
  * Query graph filtering.
@@ -24,14 +24,14 @@ import { getQuerySemanticDiagnostics } from './query-inspection.js';
  *
  * 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
+ * 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}
+ * @see {@link ../../../docs/decisions/query-language.md}
+ * @see {@link ../load-project-graph.js}
  */
 
 export const DEFAULT_QUERY_LIMIT = 25;

package/lib/{query-inspection.d.ts → graph/query/inspect.d.ts}

@@ -2,7 +2,7 @@
  * @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 {import('../parse-where-clause.types.d.ts').ParsedFieldTerm | import('../parse-where-clause.types.d.ts').ParsedFieldSetTerm} FieldDiagnosticTerm
  */
 /**
  * @typedef {{ query_source: QuerySource, where_clause: string }} ResolvedWhereClause
@@ -41,10 +41,13 @@ export function inspectQuery(repo_config: PatramRepoConfig, resolved_where_claus
  * Render a successful query inspection in one output mode.
  *
  * @param {QueryInspectionSuccess} query_inspection
- * @param {ResolvedOutputMode} output_mode
+ * @param {{ color_enabled: boolean, renderer_name: 'json' | 'plain' | 'rich' }} output_mode
  * @returns {string}
  */
-export function renderQueryInspection(query_inspection: QueryInspectionSuccess, output_mode: ResolvedOutputMode): string;
+export function renderQueryInspection(query_inspection: QueryInspectionSuccess, output_mode: {
+    color_enabled: boolean;
+    renderer_name: "json" | "plain" | "rich";
+}): string;
 /**
  * Collect schema-aware diagnostics for one parsed where clause.
  *
@@ -60,7 +63,7 @@ export type QuerySource = {
     kind: "stored_query";
     name: string;
 };
-export type FieldDiagnosticTerm = import("./parse-where-clause.types.ts").ParsedFieldTerm | import("./parse-where-clause.types.ts").ParsedFieldSetTerm;
+export type FieldDiagnosticTerm = import("../parse-where-clause.types.d.ts").ParsedFieldTerm | import("../parse-where-clause.types.d.ts").ParsedFieldSetTerm;
 export type ResolvedWhereClause = {
     query_source: QuerySource;
     where_clause: string;
@@ -80,7 +83,6 @@ export type QueryInspectionSuccess = {
     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';
+import type { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
+import type { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';
+import type { ParsedExpression } from '../parse-where-clause.types.d.ts';

package/lib/{query-inspection.js → graph/query/inspect.js}

@@ -1,26 +1,25 @@
 /* eslint-disable max-lines */
 /**
- * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
- * @import { ResolvedOutputMode } from './output-view.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from '../../config/load-patram-config.types.ts';
  * @import {
  *   ParsedExpression,
  *   ParsedRelationTargetTerm,
  *   ParsedRelationTerm,
  *   ParsedTerm,
  *   ParsedTraversalTerm,
- * } from './parse-where-clause.types.ts';
+ * } from '../parse-where-clause.types.ts';
  */
 
 import { Ansis } from 'ansis';
 
-import { parseWhereClause } from './parse-where-clause.js';
+import { parseWhereClause } from './parse.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 {import('../parse-where-clause.types.ts').ParsedFieldTerm | import('../parse-where-clause.types.ts').ParsedFieldSetTerm} FieldDiagnosticTerm
  */
 
 /**
@@ -114,7 +113,7 @@ export function inspectQuery(
  * Render a successful query inspection in one output mode.
  *
  * @param {QueryInspectionSuccess} query_inspection
- * @param {ResolvedOutputMode} output_mode
+ * @param {{ color_enabled: boolean, renderer_name: 'json' | 'plain' | 'rich' }} output_mode
  * @returns {string}
  */
 export function renderQueryInspection(query_inspection, output_mode) {
@@ -175,7 +174,7 @@ export function getQuerySemanticDiagnostics(
  * @param {ParsedExpression} expression
  * @param {PatramDiagnostic[]} diagnostics
  * @param {Set<string>} known_relation_names
- * @param {Record<string, import('./load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
+ * @param {Record<string, import('../../config/load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
  * @param {string} diagnostic_path
  */
 function collectExpressionDiagnostics(
@@ -230,7 +229,7 @@ function collectExpressionDiagnostics(
  * @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 {Record<string, import('../../config/load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
  * @param {string} diagnostic_path
  */
 function collectTermDiagnostics(
@@ -293,7 +292,7 @@ function collectTermDiagnostics(
 /**
  * @param {FieldDiagnosticTerm} term
  * @param {PatramDiagnostic[]} diagnostics
- * @param {Record<string, import('./load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
+ * @param {Record<string, import('../../config/load-patram-config.types.ts').MetadataFieldConfig>} known_field_definitions
  * @param {string} diagnostic_path
  */
 function collectFieldDiagnostics(
@@ -302,12 +301,12 @@ function collectFieldDiagnostics(
   known_field_definitions,
   diagnostic_path,
 ) {
-  const field_diagnostics_collector = getFieldDiagnosticsCollector(
+  const fieldDiagnosticsCollector = getFieldDiagnosticsCollector(
     term.field_name,
   );
 
-  if (field_diagnostics_collector) {
-    field_diagnostics_collector(term, diagnostics, diagnostic_path);
+  if (fieldDiagnosticsCollector) {
+    fieldDiagnosticsCollector(term, diagnostics, diagnostic_path);
     return;
   }
 
@@ -430,8 +429,8 @@ function collectStructuralFieldDiagnostics(term, diagnostics, diagnostic_path) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedFieldTerm} term
- * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @param {import('../parse-where-clause.types.ts').ParsedFieldTerm} term
+ * @param {import('../../config/load-patram-config.types.ts').MetadataFieldConfig} field_definition
  * @param {string} diagnostic_path
  * @returns {PatramDiagnostic | null}
  */
@@ -454,7 +453,7 @@ function getMetadataFieldOperatorDiagnostic(
 
 /**
  * @param {string} operator
- * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @param {import('../../config/load-patram-config.types.ts').MetadataFieldConfig} field_definition
  * @returns {boolean}
  */
 function supportsMetadataFieldOperator(operator, field_definition) {
@@ -474,7 +473,7 @@ function supportsMetadataFieldOperator(operator, field_definition) {
 }
 
 /**
- * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @param {import('../../config/load-patram-config.types.ts').MetadataFieldConfig} field_definition
  * @returns {boolean}
  */
 function supportsPrefixOperator(field_definition) {
@@ -489,7 +488,7 @@ function supportsPrefixOperator(field_definition) {
 }
 
 /**
- * @param {import('./load-patram-config.types.ts').MetadataFieldConfig} field_definition
+ * @param {import('../../config/load-patram-config.types.ts').MetadataFieldConfig} field_definition
  * @returns {boolean}
  */
 function supportsContainsOperator(field_definition) {

package/lib/{parse-where-clause.d.ts → graph/query/parse.d.ts}

@@ -1,5 +1,5 @@
 /**
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';
  * @import {
  *   ParseWhereClauseResult,
  *   ParsedAggregateComparison,
@@ -9,7 +9,7 @@
  *   ParsedFieldName,
  *   ParsedTerm,
  *   ParsedTraversalTerm,
- * } from './parse-where-clause.types.ts';
+ * } from '../parse-where-clause.types.d.ts';
  */
 /**
  * @typedef {{ bindings: Record<string, string>, index: number, where_clause: string }} ParserState
@@ -69,7 +69,7 @@ export type ParseValueResult = {
     success: true;
     value: string;
 } | ParseFailureResult;
-import type { ParseWhereClauseResult } from './parse-where-clause.types.ts';
-import type { PatramDiagnostic } from './load-patram-config.types.ts';
-import type { ParsedExpression } from './parse-where-clause.types.ts';
-import type { ParsedTerm } from './parse-where-clause.types.ts';
+import type { ParseWhereClauseResult } from '../parse-where-clause.types.d.ts';
+import type { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';
+import type { ParsedExpression } from '../parse-where-clause.types.d.ts';
+import type { ParsedTerm } from '../parse-where-clause.types.d.ts';

package/lib/{parse-where-clause.js → graph/query/parse.js}

@@ -1,6 +1,6 @@
 /* eslint-disable max-lines */
 /**
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramDiagnostic } from '../../config/load-patram-config.types.ts';
  * @import {
  *   ParseWhereClauseResult,
  *   ParsedAggregateComparison,
@@ -10,7 +10,7 @@
  *   ParsedFieldName,
  *   ParsedTerm,
  *   ParsedTraversalTerm,
- * } from './parse-where-clause.types.ts';
+ * } from '../parse-where-clause.types.ts';
  */
 
 /**

package/lib/graph/query/resolve.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
+ */
+/**
+ * Resolve an ad hoc or stored query into a where clause.
+ *
+ * @param {PatramRepoConfig} repo_config
+ * @param {string[]} command_arguments
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { error: CliParseError, success: false }}
+ */
+export function resolveWhereClause(repo_config: PatramRepoConfig, command_arguments: string[]): {
+    success: true;
+    value: {
+        query_source: QuerySource;
+        where_clause: string;
+    };
+} | {
+    error: CliParseError;
+    success: false;
+};
+export type QuerySource = {
+    kind: "ad_hoc";
+} | {
+    kind: "stored_query";
+    name: string;
+};
+import type { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
+import type { CliParseError } from '../../cli/arguments.types.d.ts';

package/lib/{resolve-where-clause.js → graph/query/resolve.js}

@@ -1,7 +1,10 @@
 /**
- * @import { PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { CliParseError } from '../../cli/arguments.types.ts';
+ * @import { PatramRepoConfig } from '../../config/load-patram-config.types.ts';
  */
 
+import { findCloseMatch } from '../../find-close-match.js';
+
 /**
  * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
  */
@@ -11,7 +14,7 @@
  *
  * @param {PatramRepoConfig} repo_config
  * @param {string[]} command_arguments
- * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { success: false, message: string }}
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { error: CliParseError, success: false }}
  */
 export function resolveWhereClause(repo_config, command_arguments) {
   if (command_arguments[0] === '--where') {
@@ -19,7 +22,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
     if (where_clause.length === 0) {
       return {
-        message: 'Query requires a where clause.',
+        error: {
+          code: 'message',
+          message: 'Query requires a where clause.',
+        },
         success: false,
       };
     }
@@ -39,7 +45,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
   if (!stored_query_name) {
     return {
-      message: 'Query requires "--where" or a stored query name.',
+      error: {
+        code: 'message',
+        message: 'Query requires "--where" or a stored query name.',
+      },
       success: false,
     };
   }
@@ -48,7 +57,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
   if (!stored_query) {
     return {
-      message: `Stored query "${stored_query_name}" was not found.`,
+      error: createUnknownStoredQueryError(
+        stored_query_name,
+        Object.keys(repo_config.queries),
+      ),
       success: false,
     };
   }
@@ -64,3 +76,25 @@ export function resolveWhereClause(repo_config, command_arguments) {
     },
   };
 }
+
+/**
+ * @param {string} stored_query_name
+ * @param {string[]} stored_query_names
+ * @returns {CliParseError}
+ */
+function createUnknownStoredQueryError(stored_query_name, stored_query_names) {
+  const suggestion = findCloseMatch(stored_query_name, stored_query_names);
+
+  if (!suggestion) {
+    return {
+      code: 'unknown_stored_query',
+      name: stored_query_name,
+    };
+  }
+
+  return {
+    code: 'unknown_stored_query',
+    name: stored_query_name,
+    suggestion,
+  };
+}

package/lib/graph/reverse-reference-test-helpers.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared reverse-reference graph fixtures for tests.
+ */
+export function createDecisionNode(): {
+    $class: string;
+    $id: string;
+    $path: string;
+    id: string;
+    path: string;
+    status: string;
+    title: string;
+};
+export function createReconcileNode(): {
+    $class: string;
+    $id: string;
+    $path: string;
+    id: string;
+    path: string;
+    title: string;
+};
+export function createResumeNode(): {
+    $class: string;
+    $id: string;
+    $path: string;
+    id: string;
+    path: string;
+    title: string;
+};
+export function createTaskNode(): {
+    $class: string;
+    $id: string;
+    $path: string;
+    id: string;
+    path: string;
+    status: string;
+    title: string;
+};
+/**
+ * @param {string} edge_id
+ * @param {string} from_id
+ * @param {string} origin_path
+ * @param {string} relation_name
+ * @param {string} to_id
+ */
+export function createGraphEdge(edge_id: string, from_id: string, origin_path: string, relation_name: string, to_id: string): {
+    from: string;
+    id: string;
+    origin: {
+        column: number;
+        line: number;
+        path: string;
+    };
+    relation: string;
+    to: string;
+};

package/lib/{command-output.js → output/command-output.js}

@@ -1,12 +1,12 @@
 /**
- * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
+ * @import { ParsedCliArguments } from '../cli/arguments.types.ts';
  * @import { OutputView } from './output-view.types.ts';
  */
 
 import process from 'node:process';
 
+import { resolveOutputMode } from '../cli/resolve-output-mode.js';
 import { renderOutputView } from './render-output-view.js';
-import { resolveOutputMode } from './resolve-output-mode.js';
 import { writePagedOutput } from './write-paged-output.js';
 
 /**
@@ -17,11 +17,11 @@ import { writePagedOutput } from './write-paged-output.js';
  *
  * Kind: output
  * Status: active
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/tty-pager-output.md
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/tty-pager-output.md
  * @patram
  * @see {@link ./render-output-view.js}
- * @see {@link ../docs/decisions/tty-pager-output.md}
+ * @see {@link ../../docs/decisions/tty-pager-output.md}
  */
 
 /**

package/lib/{derived-summary.js → output/derived-summary.js}

@@ -1,10 +1,10 @@
 /**
- * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
+ * @import { BuildGraphResult, GraphNode } from '../graph/build-graph.types.ts';
  * @import { OutputDerivedSummary } from './output-view.types.ts';
- * @import { DerivedSummaryConfig, DerivedSummaryFieldConfig, DerivedSummaryScalar, PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { DerivedSummaryConfig, DerivedSummaryFieldConfig, DerivedSummaryScalar, PatramRepoConfig } from '../config/load-patram-config.types.ts';
  */
 
-import { queryGraph } from './query-graph.js';
+import { queryGraph } from '../graph/query/execute.js';
 
 /**
  * Derived summary evaluation.
@@ -14,11 +14,11 @@ import { queryGraph } from './query-graph.js';
  *
  * Kind: output
  * Status: active
- * Tracked in: ../docs/plans/v0/declarative-derived-summaries.md
- * Decided by: ../docs/decisions/declarative-derived-summary-config.md
- * Decided by: ../docs/decisions/declarative-derived-summary-side-effects.md
+ * Tracked in: ../../docs/plans/v0/declarative-derived-summaries.md
+ * Decided by: ../../docs/decisions/declarative-derived-summary-config.md
+ * Decided by: ../../docs/decisions/declarative-derived-summary-side-effects.md
  * @patram
- * @see {@link ./load-patram-config.js}
+ * @see {@link ../config/load-patram-config.js}
  * @see {@link ./render-output-view.js}
  */
 

package/lib/{layout-incoming-references.js → output/layout-incoming-references.js}

@@ -17,9 +17,9 @@ import { formatOutputItemBlock } from './format-output-item-block.js';
  * @returns {string[]}
  */
 export function layoutIncomingReferenceLines(incoming, layout_options = {}) {
-  const format_node_header =
+  const formatNodeHeader =
     layout_options.format_node_header ?? defaultNodeHeaderFormatter;
-  const format_relation_header =
+  const formatRelationHeader =
     layout_options.format_relation_header ?? defaultRelationHeaderFormatter;
   /** @type {string[]} */
   const output_lines = [];
@@ -32,10 +32,10 @@ export function layoutIncomingReferenceLines(incoming, layout_options = {}) {
     const relation_sources = incoming[relation_name];
 
     output_lines.push(
-      format_relation_header(relation_name, relation_sources.length),
+      formatRelationHeader(relation_name, relation_sources.length),
     );
     output_lines.push(
-      ...layoutIncomingRelationSources(relation_sources, format_node_header),
+      ...layoutIncomingRelationSources(relation_sources, formatNodeHeader),
     );
   }
 

package/lib/{layout-incoming-summary-lines.js → output/layout-incoming-summary-lines.js}

@@ -8,11 +8,6 @@ export function layoutIncomingSummaryLines(incoming_summary) {
   const relation_names = Object.keys(incoming_summary);
   const output_lines = ['incoming refs:'];
 
-  if (relation_names.length === 0) {
-    output_lines.push('  none');
-    return output_lines;
-  }
-
   for (const relation_name of relation_names) {
     output_lines.push(`  ${relation_name}: ${incoming_summary[relation_name]}`);
   }