patram 0.11.0 → 0.12.0

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

@@ -0,0 +1,42 @@
+/**
+ * @import { GraphNode } from './build-graph.types.d.ts';
+ */
+/**
+ * @typedef {GraphNode &
+ *   Record<string, unknown> & {
+ *     $class?: string,
+ *     $path?: string,
+ *     id?: string,
+ *     kind?: string,
+ *     path?: string,
+ *   }} GraphNodeLike
+ */
+/**
+ * @param {GraphNode | undefined} graph_node
+ * @returns {string}
+ */
+export function getGraphNodeId(graph_node: GraphNode | undefined): string;
+/**
+ * @param {GraphNode | undefined} graph_node
+ * @returns {string | undefined}
+ */
+export function getGraphNodeClassName(graph_node: GraphNode | undefined): string | undefined;
+/**
+ * @param {GraphNode | undefined} graph_node
+ * @returns {string | undefined}
+ */
+export function getGraphNodePath(graph_node: GraphNode | undefined): string | undefined;
+/**
+ * @param {GraphNode | undefined} graph_node
+ * @param {string} field_name
+ * @returns {GraphNode['metadata'][string] | undefined}
+ */
+export function getGraphNodeMetadataValue(graph_node: GraphNode | undefined, field_name: string): GraphNode["metadata"][string] | undefined;
+export type GraphNodeLike = GraphNode & Record<string, unknown> & {
+    $class?: string;
+    $path?: string;
+    id?: string;
+    kind?: string;
+    path?: string;
+};
+import type { GraphNode } from './build-graph.types.d.ts';

package/lib/graph/graph-node.js

@@ -0,0 +1,83 @@
+/**
+ * @import { GraphNode } from './build-graph.types.ts';
+ */
+
+/**
+ * @typedef {GraphNode &
+ *   Record<string, unknown> & {
+ *     $class?: string,
+ *     $path?: string,
+ *     id?: string,
+ *     kind?: string,
+ *     path?: string,
+ *   }} GraphNodeLike
+ */
+
+/**
+ * @param {GraphNode | undefined} graph_node
+ * @returns {string}
+ */
+export function getGraphNodeId(graph_node) {
+  if (!graph_node) {
+    throw new Error('Expected a graph node.');
+  }
+
+  const legacy_graph_node = /** @type {GraphNodeLike} */ (graph_node);
+
+  return graph_node.identity?.id ?? legacy_graph_node.id ?? '';
+}
+
+/**
+ * @param {GraphNode | undefined} graph_node
+ * @returns {string | undefined}
+ */
+export function getGraphNodeClassName(graph_node) {
+  if (!graph_node) {
+    return undefined;
+  }
+
+  const legacy_graph_node = /** @type {GraphNodeLike} */ (graph_node);
+
+  return (
+    graph_node.identity?.class_name ??
+    legacy_graph_node.$class ??
+    legacy_graph_node.kind
+  );
+}
+
+/**
+ * @param {GraphNode | undefined} graph_node
+ * @returns {string | undefined}
+ */
+export function getGraphNodePath(graph_node) {
+  if (!graph_node) {
+    return undefined;
+  }
+
+  const legacy_graph_node = /** @type {GraphNodeLike} */ (graph_node);
+
+  return (
+    graph_node.identity?.path ??
+    legacy_graph_node.$path ??
+    legacy_graph_node.path
+  );
+}
+
+/**
+ * @param {GraphNode | undefined} graph_node
+ * @param {string} field_name
+ * @returns {GraphNode['metadata'][string] | undefined}
+ */
+export function getGraphNodeMetadataValue(graph_node, field_name) {
+  if (!graph_node) {
+    return undefined;
+  }
+
+  if (graph_node.metadata) {
+    return graph_node.metadata[field_name];
+  }
+
+  return /** @type {GraphNode['metadata'][string] | undefined} */ (
+    /** @type {GraphNodeLike} */ (graph_node)[field_name]
+  );
+}

package/lib/graph/inspect-reverse-references.js

@@ -7,6 +7,7 @@ import {
   normalizeRepoRelativePath,
   resolveDocumentNodeId,
 } from './document-node-identity.js';
+import { getGraphNodeId } from './graph-node.js';
 import { queryGraph } from './query/execute.js';
 
 /**
@@ -30,7 +31,7 @@ export function inspectReverseReferences(
 ) {
   const normalized_target_path = normalizeRepoRelativePath(target_file_path);
   const target_node_id = resolveDocumentNodeId(
-    graph.document_node_ids,
+    graph.document_path_ids,
     normalized_target_path,
   );
   const target_node =
@@ -52,7 +53,7 @@ export function inspectReverseReferences(
     diagnostics: [],
     incoming: collectIncomingGroups(
       graph,
-      target_node.id,
+      getGraphNodeId(target_node),
       allowed_source_node_ids,
     ),
     node: target_node,
@@ -94,7 +95,7 @@ function collectIncomingGroups(graph, target_node_id, allowed_source_node_ids) {
       grouped_incoming.set(graph_edge.relation, relation_sources);
     }
 
-    relation_sources.set(source_node.id, source_node);
+    relation_sources.set(getGraphNodeId(source_node), source_node);
   }
 
   return formatIncomingGroups(grouped_incoming);
@@ -123,7 +124,9 @@ function resolveAllowedSourceNodeIds(graph, where_clause, repo_config) {
     };
   }
 
-  return new Set(query_result.nodes.map((graph_node) => graph_node.id));
+  return new Set(
+    query_result.nodes.map((graph_node) => getGraphNodeId(graph_node)),
+  );
 }
 
 /**
@@ -156,12 +159,14 @@ function formatIncomingGroups(grouped_incoming) {
  */
 function createFallbackTargetNode(node_id, target_path) {
   return {
-    $class: 'document',
-    $id: node_id,
-    $path: target_path,
-    id: node_id,
-    path: target_path,
-    title: target_path,
+    identity: {
+      class_name: 'document',
+      id: node_id,
+      path: target_path,
+    },
+    metadata: {
+      title: target_path,
+    },
   };
 }
 
@@ -171,7 +176,7 @@ function createFallbackTargetNode(node_id, target_path) {
  * @returns {number}
  */
 function compareGraphNodes(left_node, right_node) {
-  return compareStrings(left_node.id, right_node.id);
+  return compareStrings(getGraphNodeId(left_node), getGraphNodeId(right_node));
 }
 
 /**

package/lib/graph/load-project-graph.d.ts

@@ -4,13 +4,13 @@
  * Loads config, scans source files, parses claims, and materializes the graph
  * used by CLI commands.
  *
- * 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
+ * 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
  * @patram
  * @see {@link ../parse/parse-claims.js}
  * @see {@link ./build-graph.js}

package/lib/graph/load-project-graph.js

@@ -19,13 +19,13 @@ import { resolvePatramGraphConfig } from '../config/resolve-patram-graph-config.
  * Loads config, scans source files, parses claims, and materializes the graph
  * used by CLI commands.
  *
- * 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
+ * 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
  * @patram
  * @see {@link ../parse/parse-claims.js}
  * @see {@link ./build-graph.js}

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

@@ -4,7 +4,7 @@ export interface ParsedFieldTerm {
     column: number;
     field_name: ParsedFieldName;
     kind: 'field';
-    operator: '!=' | '<' | '<=' | '=' | '>' | '>=' | '^=' | '~';
+    operator: '$=' | '*=' | '<' | '<=' | '<>' | '=' | '>' | '>=' | '^=' | '~';
     value: string;
 }
 export interface ParsedFieldSetTerm {
@@ -30,7 +30,7 @@ export interface ParsedRelationTargetTerm {
     relation_name: string;
     target_id: string;
 }
-export type ParsedAggregateComparison = '!=' | '<' | '<=' | '=' | '>' | '>=';
+export type ParsedAggregateComparison = '<' | '<=' | '<>' | '=' | '>' | '>=';
 export type ParsedAggregateName = 'any' | 'count' | 'none';
 export interface ParsedAggregateTerm {
     aggregate_name: ParsedAggregateName;
@@ -61,3 +61,4 @@ export type ParseWhereClauseResult = {
     diagnostic: PatramDiagnostic;
     success: false;
 };
+export type ParseQueryResult = ParseWhereClauseResult;

package/lib/graph/query/cypher-reader.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} message
+ * @returns {{diagnostic: $k$$k$$l$$k$$k$$l$config$l$load$j$patram$j$config$k$types$k$ts.PatramDiagnostic, success: false}}
+ */
+export function failAtCurrent(parser_state: CypherParserState, message: string): {
+    diagnostic: $k$$k$$l$$k$$k$$l$config$l$load$j$patram$j$config$k$types$k$ts.PatramDiagnostic;
+    success: false;
+};
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} keyword
+ * @returns {CypherToken}
+ */
+export function expectKeyword(parser_state: CypherParserState, keyword: string): CypherToken;
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} symbol
+ * @returns {CypherToken}
+ */
+export function expectSymbol(parser_state: CypherParserState, symbol: string): CypherToken;
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} keyword
+ * @returns {boolean}
+ */
+export function consumeKeyword(parser_state: CypherParserState, keyword: string): boolean;
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} symbol
+ * @returns {boolean}
+ */
+export function consumeSymbol(parser_state: CypherParserState, symbol: string): boolean;
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} keyword
+ * @returns {boolean}
+ */
+export function peekKeyword(parser_state: CypherParserState, keyword: string): boolean;
+/**
+ * @param {CypherParserState} parser_state
+ * @param {number} offset
+ * @param {string} symbol
+ * @returns {boolean}
+ */
+export function peekSymbolAt(parser_state: CypherParserState, offset: number, symbol: string): boolean;
+/**
+ * @param {CypherParserState} parser_state
+ * @returns {CypherToken | undefined}
+ */
+export function consumeToken(parser_state: CypherParserState): CypherToken | undefined;
+/**
+ * @param {CypherParserState} parser_state
+ * @returns {CypherToken | undefined}
+ */
+export function peekToken(parser_state: CypherParserState): CypherToken | undefined;
+import type { CypherParserState } from './cypher.types.d.ts';
+import type * as $k$$k$$l$$k$$k$$l$config$l$load$j$patram$j$config$k$types$k$ts from '../../config/load-patram-config.types.d.ts';
+import type { CypherToken } from './cypher.types.d.ts';

package/lib/graph/query/cypher-reader.js

@@ -0,0 +1,151 @@
+/** @import * as $k$$k$$l$$k$$k$$l$config$l$load$j$patram$j$config$k$types$k$ts from '../../config/load-patram-config.types.ts'; */
+/**
+ * @import { CypherParserState, CypherToken } from './cypher.types.ts';
+ */
+
+import { fail } from './cypher-support.js';
+
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} message
+ * @returns {{diagnostic: $k$$k$$l$$k$$k$$l$config$l$load$j$patram$j$config$k$types$k$ts.PatramDiagnostic, success: false}}
+ */
+export function failAtCurrent(parser_state, message) {
+  const token = peekToken(parser_state);
+
+  return fail(
+    token ? token.column : parser_state.query_text.length + 1,
+    message,
+  );
+}
+
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} keyword
+ * @returns {CypherToken}
+ */
+export function expectKeyword(parser_state, keyword) {
+  const token = consumeToken(parser_state);
+
+  if (!isKeywordToken(token, keyword)) {
+    throw new Error(`Expected the ${keyword} keyword.`);
+  }
+
+  return /** @type {CypherToken} */ (token);
+}
+
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} symbol
+ * @returns {CypherToken}
+ */
+export function expectSymbol(parser_state, symbol) {
+  const token = consumeToken(parser_state);
+
+  if (!isSymbolToken(token, symbol)) {
+    throw new Error(`Expected the "${symbol}" token.`);
+  }
+
+  return /** @type {CypherToken} */ (token);
+}
+
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} keyword
+ * @returns {boolean}
+ */
+export function consumeKeyword(parser_state, keyword) {
+  const token = peekToken(parser_state);
+
+  if (!isKeywordToken(token, keyword)) {
+    return false;
+  }
+
+  parser_state.index += 1;
+  return true;
+}
+
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} symbol
+ * @returns {boolean}
+ */
+export function consumeSymbol(parser_state, symbol) {
+  const token = peekToken(parser_state);
+
+  if (!isSymbolToken(token, symbol)) {
+    return false;
+  }
+
+  parser_state.index += 1;
+  return true;
+}
+
+/**
+ * @param {CypherParserState} parser_state
+ * @param {string} keyword
+ * @returns {boolean}
+ */
+export function peekKeyword(parser_state, keyword) {
+  return isKeywordToken(peekToken(parser_state), keyword);
+}
+
+/**
+ * @param {CypherParserState} parser_state
+ * @param {number} offset
+ * @param {string} symbol
+ * @returns {boolean}
+ */
+export function peekSymbolAt(parser_state, offset, symbol) {
+  return isSymbolToken(
+    parser_state.tokens[parser_state.index + offset],
+    symbol,
+  );
+}
+
+/**
+ * @param {CypherParserState} parser_state
+ * @returns {CypherToken | undefined}
+ */
+export function consumeToken(parser_state) {
+  const token = parser_state.tokens[parser_state.index];
+
+  if (token === undefined) {
+    return undefined;
+  }
+
+  parser_state.index += 1;
+  return token;
+}
+
+/**
+ * @param {CypherParserState} parser_state
+ * @returns {CypherToken | undefined}
+ */
+export function peekToken(parser_state) {
+  return parser_state.tokens[parser_state.index];
+}
+
+/**
+ * @param {CypherToken | undefined} token
+ * @param {string} keyword
+ * @returns {boolean}
+ */
+function isKeywordToken(token, keyword) {
+  return (
+    token !== undefined &&
+    token.kind === 'identifier' &&
+    token.value.toUpperCase() === keyword
+  );
+}
+
+/**
+ * @param {CypherToken | undefined} token
+ * @param {string} symbol
+ * @returns {boolean}
+ */
+function isSymbolToken(token, symbol) {
+  return (
+    token !== undefined && token.kind === 'symbol' && token.value === symbol
+  );
+}

package/lib/graph/query/cypher-support.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @import { PatramDiagnostic, PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
+ * @import {
+ *   ParsedAggregateComparison,
+ *   ParsedExpression,
+ *   ParsedFieldTerm,
+ *   ParsedTerm,
+ * } from '../parse-where-clause.types.d.ts';
+ * @import { CypherNodePattern } from './cypher.types.d.ts';
+ */
+/**
+ * @param {number} column
+ * @param {string} message
+ * @returns {{ diagnostic: PatramDiagnostic, success: false }}
+ */
+export function fail(column: number, message: string): {
+    diagnostic: PatramDiagnostic;
+    success: false;
+};
+/**
+ * @param {string} relation_type
+ * @returns {string}
+ */
+export function relationTypeToRelationName(relation_type: string): string;
+/**
+ * @param {string} value
+ * @returns {value is ParsedAggregateComparison}
+ */
+export function isAggregateComparison(value: string): value is ParsedAggregateComparison;
+/**
+ * @param {CypherNodePattern} node_pattern
+ * @param {PatramRepoConfig | null} repo_config
+ * @returns {ParsedExpression | null}
+ */
+export function createNodeLabelExpression(node_pattern: CypherNodePattern, repo_config: PatramRepoConfig | null): ParsedExpression | null;
+/**
+ * @param {string} field_name
+ * @param {ParsedFieldTerm['operator']} operator
+ * @param {string} value
+ * @param {number} column
+ * @returns {{ success: true, expression: ParsedExpression }}
+ */
+export function createFieldExpression(field_name: string, operator: ParsedFieldTerm["operator"], value: string, column: number): {
+    success: true;
+    expression: ParsedExpression;
+};
+/**
+ * @param {string} field_name
+ * @param {'in' | 'not in'} operator
+ * @param {string[]} values
+ * @param {number} column
+ * @returns {{ success: true, expression: ParsedExpression }}
+ */
+export function createFieldSetExpression(field_name: string, operator: "in" | "not in", values: string[], column: number): {
+    success: true;
+    expression: ParsedExpression;
+};
+/**
+ * @param {number} column
+ * @returns {ParsedExpression}
+ */
+export function createAlwaysTrueExpression(column: number): ParsedExpression;
+/**
+ * @param {ParsedExpression[]} expressions
+ * @returns {ParsedExpression}
+ */
+export function collapseAndExpressions(expressions: ParsedExpression[]): ParsedExpression;
+/**
+ * @param {'and' | 'or'} kind
+ * @param {ParsedExpression[]} expressions
+ * @returns {ParsedExpression}
+ */
+export function collapseBooleanExpression(kind: "and" | "or", expressions: ParsedExpression[]): ParsedExpression;
+import type { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';
+import type { ParsedAggregateComparison } from '../parse-where-clause.types.d.ts';
+import type { CypherNodePattern } from './cypher.types.d.ts';
+import type { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
+import type { ParsedExpression } from '../parse-where-clause.types.d.ts';
+import type { ParsedFieldTerm } from '../parse-where-clause.types.d.ts';