patram 0.8.0 → 0.9.0

package/lib/{build-graph.js → graph/build-graph.js}

@@ -1,9 +1,9 @@
 /* eslint-disable max-lines */
 /**
  * @import { BuildGraphResult, GraphEdge, GraphNode } from './build-graph.types.ts';
- * @import { PatramClaim } from './parse-claims.types.ts';
- * @import { MetadataFieldConfig } from './load-patram-config.types.ts';
- * @import { MappingDefinition, PatramConfig } from './patram-config.types.ts';
+ * @import { PatramClaim } from '../parse/parse-claims.types.ts';
+ * @import { MetadataFieldConfig } from '../config/load-patram-config.types.ts';
+ * @import { MappingDefinition, PatramConfig } from '../config/patram-config.types.ts';
  */
 
 import { posix } from 'node:path';
@@ -25,17 +25,17 @@ import {
  *
  * Kind: graph
  * Status: active
- * Uses Term: ../docs/reference/terms/claim.md
- * Uses Term: ../docs/reference/terms/document.md
- * Uses Term: ../docs/reference/terms/graph.md
- * Uses Term: ../docs/reference/terms/mapping.md
- * Uses Term: ../docs/reference/terms/relation.md
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/graph-materialization.md
- * Implements: ../docs/tasks/v0/materialize-graph.md
+ * Uses Term: ../../docs/reference/terms/claim.md
+ * Uses Term: ../../docs/reference/terms/document.md
+ * Uses Term: ../../docs/reference/terms/graph.md
+ * Uses Term: ../../docs/reference/terms/mapping.md
+ * Uses Term: ../../docs/reference/terms/relation.md
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/graph-materialization.md
+ * Implements: ../../docs/tasks/v0/materialize-graph.md
  * @patram
  * @see {@link ./load-project-graph.js}
- * @see {@link ../docs/decisions/graph-materialization.md}
+ * @see {@link ../../docs/decisions/graph-materialization.md}
  */
 
 const STRUCTURAL_FIELD_NAMES = new Set(['$class', '$id', '$path']);
@@ -712,8 +712,12 @@ function setSingleValueField(graph_node, field_name, field_value) {
   }
 
   if (current_value !== field_value) {
+    const current_value_text = Array.isArray(current_value)
+      ? current_value.join(', ')
+      : current_value;
+
     throw new Error(
-      `Node "${graph_node.id}" has conflicting values for field "${field_name}": "${current_value}" and "${field_value}".`,
+      `Node "${graph_node.id}" has conflicting values for field "${field_name}": "${current_value_text}" and "${field_value}".`,
     );
   }
 }

package/lib/{build-graph.types.d.ts → graph/build-graph.types.d.ts}

@@ -1,4 +1,4 @@
-import type { ClaimOrigin } from './parse-claims.types.ts';
+import type { ClaimOrigin } from '../parse/parse-claims.types.d.ts';
 export interface GraphNode {
     $class?: string;
     $id?: string;

package/lib/graph/check-directive-metadata.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Directive and placement validation.
+ *
+ * Kind: graph
+ * Status: active
+ * Tracked in: ../../docs/plans/v0/directive-type-validation.md
+ * Decided by: ../../docs/decisions/directive-type-validation.md
+ * @see {@link ../../docs/decisions/directive-type-validation.md}
+ * @patram
+ * @see {@link ./check-graph.js}
+ */
+/**
+ * @param {BuildGraphResult} graph
+ * @param {PatramRepoConfig} repo_config
+ * @param {PatramClaim[]} claims
+ * @param {string[]} existing_file_paths
+ * @returns {PatramDiagnostic[]}
+ */
+export function checkDirectiveMetadata(graph: BuildGraphResult, repo_config: PatramRepoConfig, claims: PatramClaim[], existing_file_paths: string[]): PatramDiagnostic[];
+import type { BuildGraphResult } from './build-graph.types.d.ts';
+import type { PatramRepoConfig } from '../config/load-patram-config.types.d.ts';
+import type { PatramClaim } from '../parse/parse-claims.types.d.ts';
+import type { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';

package/lib/{check-directive-metadata.js → graph/check-directive-metadata.js}

@@ -1,9 +1,9 @@
 /* eslint-disable max-lines */
 /**
  * @import { BuildGraphResult } from './build-graph.types.ts';
- * @import { ClassFieldRuleConfig, MetadataFieldConfig, MetadataSchemaConfig, PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
- * @import { PatramClaim } from './parse-claims.types.ts';
- * @import { MappingDefinition } from './patram-config.types.ts';
+ * @import { ClassFieldRuleConfig, MetadataFieldConfig, MetadataSchemaConfig, PatramDiagnostic, PatramRepoConfig } from '../config/load-patram-config.types.ts';
+ * @import { PatramClaim } from '../parse/parse-claims.types.ts';
+ * @import { MappingDefinition } from '../config/patram-config.types.ts';
  */
 
 import {
@@ -18,18 +18,18 @@ import {
   createOriginDiagnostic,
 } from './directive-diagnostics.js';
 import { formatQuotedList } from './directive-type-rules.js';
-import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
+import { resolvePatramGraphConfig } from '../config/resolve-patram-graph-config.js';
 
 /**
  * Directive and placement validation.
  *
  * Kind: graph
  * Status: active
- * Tracked in: ../docs/plans/v0/directive-type-validation.md
- * Decided by: ../docs/decisions/directive-type-validation.md
+ * Tracked in: ../../docs/plans/v0/directive-type-validation.md
+ * Decided by: ../../docs/decisions/directive-type-validation.md
+ * @see {@link ../../docs/decisions/directive-type-validation.md}
  * @patram
  * @see {@link ./check-graph.js}
- * @see {@link ../docs/decisions/directive-type-validation.md}
  */
 
 /**

package/lib/graph/check-directive-path-target.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {MappingDefinition | null} mapping_definition
+ * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }> | undefined} type_definition
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Set<string>} document_paths
+ * @returns {PatramDiagnostic[]}
+ */
+export function createPathExistenceDiagnostics(claim: PatramClaim, directive_name: string, mapping_definition: MappingDefinition | null, type_definition: Exclude<DirectiveTypeConfig, {
+    type: "enum";
+}> | undefined, document_entity_keys: Map<string, string>, document_node_references: Map<string, import("./document-node-identity.js").DocumentNodeReference>, document_paths: Set<string>): PatramDiagnostic[];
+/**
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramRepoConfig} repo_config
+ * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }>} type_definition
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Set<string>} document_paths
+ * @returns {PatramDiagnostic[]}
+ */
+export function createPathClassDiagnostics(claim: PatramClaim, directive_name: string, mappings: Record<string, MappingDefinition>, repo_config: PatramRepoConfig, type_definition: Exclude<DirectiveTypeConfig, {
+    type: "enum";
+}>, document_entity_keys: Map<string, string>, document_node_references: Map<string, import("./document-node-identity.js").DocumentNodeReference>, document_paths: Set<string>): PatramDiagnostic[];
+import type { PatramClaim } from '../parse/parse-claims.types.d.ts';
+import type { MappingDefinition } from '../config/patram-config.types.d.ts';
+import type { DirectiveTypeConfig } from '../config/load-patram-config.types.d.ts';
+import type { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';
+import type { PatramRepoConfig } from '../config/load-patram-config.types.d.ts';

package/lib/{check-directive-path-target.js → graph/check-directive-path-target.js}

@@ -1,10 +1,10 @@
 /**
- * @import { DirectiveTypeConfig, PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
- * @import { PatramClaim } from './parse-claims.types.ts';
- * @import { MappingDefinition } from './patram-config.types.ts';
+ * @import { DirectiveTypeConfig, PatramDiagnostic, PatramRepoConfig } from '../config/load-patram-config.types.ts';
+ * @import { PatramClaim } from '../parse/parse-claims.types.ts';
+ * @import { MappingDefinition } from '../config/patram-config.types.ts';
  */
 
-import { isPathLikeTarget } from './claim-helpers.js';
+import { isPathLikeTarget } from '../parse/claim-helpers.js';
 import { resolveTargetReference } from './build-graph-identity.js';
 import { createOriginDiagnostic } from './directive-diagnostics.js';
 

package/lib/graph/check-directive-value.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Check one directive claim value against typed validation rules.
+ *
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramRepoConfig} repo_config
+ * @param {MetadataDirectiveRuleConfig | undefined} _directive_rule
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Set<string>} document_paths
+ * @returns {PatramDiagnostic[]}
+ */
+export function checkDirectiveValue(claim: PatramClaim, directive_name: string, mappings: Record<string, MappingDefinition>, repo_config: PatramRepoConfig, _directive_rule: MetadataDirectiveRuleConfig | undefined, document_entity_keys: Map<string, string>, document_node_references: Map<string, import("./document-node-identity.js").DocumentNodeReference>, document_paths: Set<string>): PatramDiagnostic[];
+import type { PatramClaim } from '../parse/parse-claims.types.d.ts';
+import type { MappingDefinition } from '../config/patram-config.types.d.ts';
+import type { PatramRepoConfig } from '../config/load-patram-config.types.d.ts';
+import type { MetadataDirectiveRuleConfig } from '../config/load-patram-config.types.d.ts';
+import type { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';

package/lib/{check-directive-value.js → graph/check-directive-value.js}

@@ -1,7 +1,7 @@
 /**
- * @import { DirectiveTypeConfig, MetadataDirectiveRuleConfig, PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
- * @import { PatramClaim } from './parse-claims.types.ts';
- * @import { MappingDefinition } from './patram-config.types.ts';
+ * @import { DirectiveTypeConfig, MetadataDirectiveRuleConfig, PatramDiagnostic, PatramRepoConfig } from '../config/load-patram-config.types.ts';
+ * @import { PatramClaim } from '../parse/parse-claims.types.ts';
+ * @import { MappingDefinition } from '../config/patram-config.types.ts';
  */
 
 import {

package/lib/graph/check-graph.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Graph validation.
+ *
+ * Reports broken document links and missing edge nodes after graph
+ * materialization.
+ *
+ * Kind: graph
+ * Status: active
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/check-link-target-existence.md
+ * Implements: ../../docs/tasks/v0/check-command.md
+ * @see {@link ../../docs/decisions/check-link-target-existence.md}
+ * @patram
+ * @see {@link ./build-graph.js}
+ */
+/**
+ * Check a materialized graph for broken document links and missing edge nodes.
+ *
+ * @param {BuildGraphResult} graph
+ * @param {string[]} existing_file_paths
+ * @param {PatramRepoConfig} [repo_config]
+ * @param {PatramClaim[]} [claims]
+ * @returns {PatramDiagnostic[]}
+ */
+export function checkGraph(graph: BuildGraphResult, existing_file_paths: string[], repo_config?: PatramRepoConfig, claims?: PatramClaim[]): PatramDiagnostic[];
+import type { BuildGraphResult } from './build-graph.types.d.ts';
+import type { PatramRepoConfig } from '../config/load-patram-config.types.d.ts';
+import type { PatramClaim } from '../parse/parse-claims.types.d.ts';
+import type { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';

package/lib/{check-graph.js → graph/check-graph.js}

@@ -1,7 +1,7 @@
 /**
  * @import { BuildGraphResult, GraphEdge, GraphNode } from './build-graph.types.ts';
- * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
- * @import { PatramClaim } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from '../config/load-patram-config.types.ts';
+ * @import { PatramClaim } from '../parse/parse-claims.types.ts';
  */
 
 import { checkDirectiveMetadata } from './check-directive-metadata.js';
@@ -14,12 +14,12 @@ import { checkDirectiveMetadata } from './check-directive-metadata.js';
  *
  * Kind: graph
  * Status: active
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/check-link-target-existence.md
- * Implements: ../docs/tasks/v0/check-command.md
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/check-link-target-existence.md
+ * Implements: ../../docs/tasks/v0/check-command.md
+ * @see {@link ../../docs/decisions/check-link-target-existence.md}
  * @patram
  * @see {@link ./build-graph.js}
- * @see {@link ../docs/decisions/check-link-target-existence.md}
  */
 
 /**

package/lib/graph/directive-diagnostics.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @import { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';
+ * @import { PatramClaim } from '../parse/parse-claims.types.d.ts';
+ */
+/**
+ * @param {PatramClaim} claim
+ * @param {string} code
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */
+export function createOriginDiagnostic(claim: PatramClaim, code: string, message: string): PatramDiagnostic;
+/**
+ * @param {string} document_path
+ * @param {string} code
+ * @param {string} message
+ * @returns {PatramDiagnostic}
+ */
+export function createDocumentDiagnostic(document_path: string, code: string, message: string): PatramDiagnostic;
+import type { PatramClaim } from '../parse/parse-claims.types.d.ts';
+import type { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';

package/lib/{directive-diagnostics.js → graph/directive-diagnostics.js}

@@ -1,6 +1,6 @@
 /**
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
- * @import { PatramClaim } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic } from '../config/load-patram-config.types.ts';
+ * @import { PatramClaim } from '../parse/parse-claims.types.ts';
  */
 
 /**

package/lib/graph/directive-type-rules.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @param {MetadataFieldConfig} type_definition
+ * @param {string} directive_value
+ * @returns {boolean}
+ */
+export function isDirectiveValueValid(type_definition: MetadataFieldConfig, directive_value: string): boolean;
+/**
+ * @param {string} directive_name
+ * @param {Exclude<MetadataFieldConfig['type'], 'enum'>} type_name
+ * @returns {string}
+ */
+export function getInvalidTypeMessage(directive_name: string, type_name: Exclude<MetadataFieldConfig["type"], "enum">): string;
+/**
+ * @param {string[]} values
+ * @returns {string}
+ */
+export function formatQuotedList(values: string[]): string;
+import type { MetadataFieldConfig } from '../config/load-patram-config.types.d.ts';

package/lib/{directive-type-rules.js → graph/directive-type-rules.js}

@@ -1,8 +1,8 @@
 /**
- * @import { MetadataFieldConfig } from './load-patram-config.types.ts';
+ * @import { MetadataFieldConfig } from '../config/load-patram-config.types.ts';
  */
 
-import { isPathLikeTarget } from './claim-helpers.js';
+import { isPathLikeTarget } from '../parse/claim-helpers.js';
 
 /**
  * @param {MetadataFieldConfig} type_definition
@@ -52,7 +52,7 @@ export function getInvalidTypeMessage(directive_name, type_name) {
     case 'date_time':
       return `Directive "${directive_name}" must use YYYY-MM-DD HH:MM.`;
     default:
-      throw new Error(`Unsupported directive type "${type_name}".`);
+      throw new Error('Unsupported directive type.');
   }
 }
 

package/lib/{document-node-identity.d.ts → graph/document-node-identity.d.ts}

@@ -43,5 +43,5 @@ export type DocumentNodeReference = {
     key: string;
     path: string;
 };
-import type { MappingDefinition } from './patram-config.types.ts';
-import type { PatramClaim } from './parse-claims.types.ts';
+import type { MappingDefinition } from '../config/patram-config.types.d.ts';
+import type { PatramClaim } from '../parse/parse-claims.types.d.ts';

package/lib/{document-node-identity.js → graph/document-node-identity.js}

@@ -1,6 +1,6 @@
 /**
- * @import { PatramClaim } from './parse-claims.types.ts';
- * @import { MappingDefinition } from './patram-config.types.ts';
+ * @import { PatramClaim } from '../parse/parse-claims.types.ts';
+ * @import { MappingDefinition } from '../config/patram-config.types.ts';
  */
 
 import { posix } from 'node:path';

package/lib/graph/inspect-reverse-references.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Inspect incoming graph edges for one canonical target file.
+ *
+ * @param {BuildGraphResult} graph
+ * @param {string} target_file_path
+ * @param {PatramRepoConfig | undefined} repo_config
+ * @param {string | undefined} where_clause
+ * @returns {{
+ *   diagnostics: PatramDiagnostic[],
+ *   incoming: Record<string, GraphNode[]>,
+ *   node: GraphNode,
+ * }}
+ */
+export function inspectReverseReferences(graph: BuildGraphResult, target_file_path: string, repo_config: PatramRepoConfig | undefined, where_clause: string | undefined): {
+    diagnostics: PatramDiagnostic[];
+    incoming: Record<string, GraphNode[]>;
+    node: GraphNode;
+};
+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/{inspect-reverse-references.js → graph/inspect-reverse-references.js}

@@ -1,13 +1,13 @@
 /**
  * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
- * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from '../config/load-patram-config.types.ts';
  */
 
 import {
   normalizeRepoRelativePath,
   resolveDocumentNodeId,
 } from './document-node-identity.js';
-import { queryGraph } from './query-graph.js';
+import { queryGraph } from './query/execute.js';
 
 /**
  * Inspect incoming graph edges for one canonical target file.

package/lib/{load-project-graph.d.ts → graph/load-project-graph.d.ts}

@@ -6,13 +6,13 @@
  *
  * Kind: graph
  * Status: active
- * Uses Term: ../docs/reference/terms/claim.md
- * Uses Term: ../docs/reference/terms/graph.md
- * Uses Term: ../docs/reference/terms/mapping.md
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/dogfood-query-graph-v0.md
+ * Uses Term: ../../docs/reference/terms/claim.md
+ * Uses Term: ../../docs/reference/terms/graph.md
+ * Uses Term: ../../docs/reference/terms/mapping.md
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/dogfood-query-graph-v0.md
  * @patram
- * @see {@link ./parse-claims.js}
+ * @see {@link ../parse/parse-claims.js}
  * @see {@link ./build-graph.js}
  */
 /**
@@ -29,7 +29,7 @@ export function loadProjectGraph(project_directory: string): Promise<{
     graph: BuildGraphResult;
     source_file_paths: string[];
 }>;
-import type { PatramClaim } from './parse-claims.types.ts';
-import type { PatramRepoConfig } from './load-patram-config.types.ts';
-import type { PatramDiagnostic } from './load-patram-config.types.ts';
-import type { BuildGraphResult } from './build-graph.types.ts';
+import type { PatramClaim } from '../parse/parse-claims.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 { BuildGraphResult } from './build-graph.types.d.ts';

package/lib/{load-project-graph.js → graph/load-project-graph.js}

@@ -1,17 +1,17 @@
 /**
  * @import { BuildGraphResult } from './build-graph.types.ts';
- * @import { PatramClaim } from './parse-claims.types.ts';
- * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { PatramClaim } from '../parse/parse-claims.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from '../config/load-patram-config.types.ts';
  */
 
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
 import { buildGraph } from './build-graph.js';
-import { listSourceFiles } from './list-source-files.js';
-import { loadPatramConfig } from './load-patram-config.js';
-import { createParseOptions, parseSourceFile } from './parse-claims.js';
-import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
+import { loadPatramConfig } from '../config/load-patram-config.js';
+import { createParseOptions, parseSourceFile } from '../parse/parse-claims.js';
+import { listSourceFiles } from '../scan/list-source-files.js';
+import { resolvePatramGraphConfig } from '../config/resolve-patram-graph-config.js';
 
 /**
  * Project graph loading pipeline.
@@ -21,13 +21,13 @@ import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
  *
  * Kind: graph
  * Status: active
- * Uses Term: ../docs/reference/terms/claim.md
- * Uses Term: ../docs/reference/terms/graph.md
- * Uses Term: ../docs/reference/terms/mapping.md
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/dogfood-query-graph-v0.md
+ * Uses Term: ../../docs/reference/terms/claim.md
+ * Uses Term: ../../docs/reference/terms/graph.md
+ * Uses Term: ../../docs/reference/terms/mapping.md
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/dogfood-query-graph-v0.md
  * @patram
- * @see {@link ./parse-claims.js}
+ * @see {@link ../parse/parse-claims.js}
  * @see {@link ./build-graph.js}
  */
 

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

@@ -1,4 +1,4 @@
-import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';
 export type ParsedFieldName = string;
 export interface ParsedFieldTerm {
     column: number;

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';