patram 0.8.0 → 0.9.0

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,30 @@
+/**
+ * @import { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
+ */
+/**
+ * @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 } } | { success: false, message: string }}
+ */
+export function resolveWhereClause(repo_config: PatramRepoConfig, command_arguments: string[]): {
+    success: true;
+    value: {
+        query_source: QuerySource;
+        where_clause: string;
+    };
+} | {
+    success: false;
+    message: string;
+};
+export type QuerySource = {
+    kind: "ad_hoc";
+} | {
+    kind: "stored_query";
+    name: string;
+};
+import type { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';

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

@@ -1,5 +1,5 @@
 /**
- * @import { PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { PatramRepoConfig } from '../../config/load-patram-config.types.ts';
  */
 
 /**

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]}`);
   }

package/lib/{layout-stored-queries.js → output/layout-stored-queries.js}

@@ -3,7 +3,7 @@
  * @import { OutputStoredQueryItem } from './output-view.types.ts';
  */
 
-import { parseWhereClause } from './parse-where-clause.js';
+import { parseWhereClause } from '../graph/query/parse.js';
 
 const MAX_STORED_QUERY_WIDTH = 100;
 const MIN_TERM_COLUMN_WIDTH = 20;
@@ -96,7 +96,7 @@ function createStoredQueryPhrases(where_clause) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @returns {StoredQuerySegment[][]}
  */
 function createExpressionPhrases(expression) {
@@ -114,7 +114,7 @@ function createExpressionPhrases(expression) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @param {'and' | 'or'} operator
  * @param {boolean} should_prefix_operator
  * @returns {StoredQuerySegment[]}
@@ -139,7 +139,7 @@ function createExpressionPhrase(expression, operator, should_prefix_operator) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @param {number} parent_precedence
  * @returns {StoredQuerySegment[]}
  */
@@ -159,7 +159,7 @@ function createExpressionSegments(expression, parent_precedence) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @returns {StoredQuerySegment[]}
  */
 function createRawExpressionSegments(expression) {
@@ -202,7 +202,7 @@ function createRawExpressionSegments(expression) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedExpression} expression
  * @returns {number}
  */
 function getExpressionPrecedence(expression) {
@@ -230,7 +230,7 @@ function getBooleanExpressionPrecedence(operator) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedTerm} term
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedTerm} term
  * @returns {StoredQuerySegment[]}
  */
 function createTermSegments(term) {
@@ -265,7 +265,7 @@ function createTermSegments(term) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedFieldSetTerm} term
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedFieldSetTerm} term
  * @returns {StoredQuerySegment[]}
  */
 function createFieldSetSegments(term) {
@@ -281,7 +281,7 @@ function createFieldSetSegments(term) {
 }
 
 /**
- * @param {import('./parse-where-clause.types.ts').ParsedAggregateTerm} term
+ * @param {import('../graph/parse-where-clause.types.ts').ParsedAggregateTerm} term
  * @returns {StoredQuerySegment[]}
  */
 function createAggregateSegments(term) {

package/lib/{list-queries.js → output/list-queries.js}

@@ -1,5 +1,5 @@
 /**
- * @import { StoredQueryConfig } from './load-patram-config.types.ts';
+ * @import { StoredQueryConfig } from '../config/load-patram-config.types.ts';
  */
 
 /**

package/lib/{render-check-output.js → output/render-check-output.js}

@@ -1,5 +1,5 @@
 /**
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramDiagnostic } from '../config/load-patram-config.types.ts';
  * @import { ResolvedOutputMode } from './output-view.types.ts';
  */
 

package/lib/{render-field-discovery.js → output/render-field-discovery.js}

@@ -1,6 +1,6 @@
 /**
  * @import { ResolvedOutputMode } from './output-view.types.ts';
- * @import { FieldDiscoveryResult, FieldDiscoverySuggestion } from './discover-fields.types.ts';
+ * @import { FieldDiscoveryResult, FieldDiscoverySuggestion } from '../scan/discover-fields.types.ts';
  */
 
 import { Ansis } from 'ansis';
@@ -135,7 +135,7 @@ function formatTextFieldSuggestion(field_suggestion, render_options) {
 
 /**
  * @param {string} section_title
- * @param {import('./discover-fields.types.ts').FieldDiscoveryEvidenceReference[]} evidence_references
+ * @param {import('../scan/discover-fields.types.ts').FieldDiscoveryEvidenceReference[]} evidence_references
  * @param {{ header: (value: string) => string, label: (value: string) => string }} render_options
  * @returns {string[]}
  */
@@ -168,7 +168,7 @@ function formatTextEvidenceSection(
 }
 
 /**
- * @param {import('./discover-fields.types.ts').FieldDiscoveryEvidenceReference} evidence_reference
+ * @param {import('../scan/discover-fields.types.ts').FieldDiscoveryEvidenceReference} evidence_reference
  * @returns {string}
  */
 function formatEvidenceReference(evidence_reference) {

package/lib/output/render-output-view.js

@@ -0,0 +1,56 @@
+/**
+ * @import { ParsedCliArguments } from '../cli/arguments.types.ts';
+ * @import { ResolvedOutputMode, OutputView } from './output-view.types.ts';
+ */
+
+import { renderJsonOutput } from './renderers/json.js';
+import { renderPlainOutput } from './renderers/plain.js';
+import { renderRichOutput } from './renderers/rich.js';
+
+/**
+ * Shared command output views.
+ *
+ * Normalizes `query`, `queries`, and `show` results into renderer-specific
+ * output models.
+ *
+ * Kind: output
+ * Status: active
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/cli-output-architecture.md
+ * @patram
+ * @see {@link ./show-document.js}
+ * @see {@link ../../docs/decisions/cli-output-architecture.md}
+ */
+
+export {
+  createOutputView,
+  createRefsOutputView,
+  createShowOutputView,
+} from './view-model/index.js';
+
+/**
+ * Render one shared output view through the resolved renderer.
+ *
+ * @param {OutputView} output_view
+ * @param {ResolvedOutputMode} output_mode
+ * @param {ParsedCliArguments} parsed_arguments
+ * @returns {Promise<string>}
+ */
+export async function renderOutputView(
+  output_view,
+  output_mode,
+  parsed_arguments,
+) {
+  if (output_mode.renderer_name === 'json') {
+    return renderJsonOutput(output_view);
+  }
+
+  if (output_mode.renderer_name === 'plain') {
+    return renderPlainOutput(output_view);
+  }
+
+  return renderRichOutput(output_view, {
+    color_enabled: output_mode.color_enabled,
+    color_mode: parsed_arguments.color_mode,
+  });
+}

package/lib/{render-json-output.js → output/renderers/json.js}

@@ -1,5 +1,5 @@
 /**
- * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView } from './output-view.types.ts';
+ * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView } from '../output-view.types.ts';
  */
 
 /**

package/lib/{render-plain-output.js → output/renderers/plain.js}

@@ -1,16 +1,16 @@
 /**
- * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, RefsOutputView, ShowOutputView } from './output-view.types.ts';
+ * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, RefsOutputView, ShowOutputView } from '../output-view.types.ts';
  */
 
 import {
   formatOutputNodeMetadataRows,
   formatResolvedLinkMetadataRows,
-} from './format-output-metadata.js';
-import { formatNodeHeader } from './format-node-header.js';
-import { formatOutputItemBlock } from './format-output-item-block.js';
-import { layoutIncomingReferenceLines } from './layout-incoming-references.js';
-import { layoutIncomingSummaryLines } from './layout-incoming-summary-lines.js';
-import { layoutStoredQueries } from './layout-stored-queries.js';
+} from '../format-output-metadata.js';
+import { formatNodeHeader } from '../format-node-header.js';
+import { formatOutputItemBlock } from '../format-output-item-block.js';
+import { layoutIncomingReferenceLines } from '../layout-incoming-references.js';
+import { layoutIncomingSummaryLines } from '../layout-incoming-summary-lines.js';
+import { layoutStoredQueries } from '../layout-stored-queries.js';
 
 /**
  * Render the canonical plain output for one output view.
@@ -172,12 +172,24 @@ function formatPlainResolvedLinkItem(output_item) {
  * @returns {string}
  */
 function renderPlainIncomingSummary(output_view) {
+  if (!hasIncomingSummary(output_view.incoming_summary)) {
+    return '';
+  }
+
   const output_lines = layoutIncomingSummaryLines(output_view.incoming_summary);
   output_lines.push('', `Hint: patram refs ${output_view.path}`);
 
   return output_lines.join('\n');
 }
 
+/**
+ * @param {Record<string, number>} incoming_summary
+ * @returns {boolean}
+ */
+function hasIncomingSummary(incoming_summary) {
+  return Object.keys(incoming_summary).length > 0;
+}
+
 /**
  * @param {string} value
  * @returns {string}