patram 0.6.2 → 0.7.0

package/lib/parse-where-clause.js

@@ -14,38 +14,51 @@
  */
 
 /**
- * @typedef {{ index: number, where_clause: string }} ParserState
+ * @typedef {{ bindings: Record<string, string>, index: number, where_clause: string }} ParserState
  */
 
 /**
  * @typedef {{
- *   expression: ParsedExpression,
- *   success: true,
- * } | {
  *   diagnostic: PatramDiagnostic,
  *   success: false,
- * }} ParseExpressionResult
+ * }} ParseFailureResult
+ */
+
+/**
+ * @typedef {{
+ *   expression: ParsedExpression,
+ *   success: true,
+ * } | ParseFailureResult} ParseExpressionResult
  */
 
 /**
  * @typedef {{
  *   success: true,
  *   term: ParsedTerm,
- * } | {
- *   diagnostic: PatramDiagnostic,
- *   success: false,
- * }} ParseTermResult
+ * } | ParseFailureResult} ParseTermResult
+ */
+
+/**
+ * @typedef {{
+ *   success: true,
+ *   value: string,
+ * } | ParseFailureResult} ParseValueResult
  */
 
 /**
  * Parse one where clause into a structured boolean expression.
  *
  * @param {string} where_clause
+ * @param {{ bindings?: Record<string, string> }=} options
  * @returns {ParseWhereClauseResult}
  */
-export function parseWhereClause(where_clause) {
+export function parseWhereClause(where_clause, options = {}) {
   /** @type {ParserState} */
-  const parser_state = { index: 0, where_clause };
+  const parser_state = {
+    bindings: options.bindings ?? {},
+    index: 0,
+    where_clause,
+  };
 
   skipWhitespace(parser_state);
 
@@ -429,15 +442,21 @@ function parseFieldSet(parser_state, start_index, field_name) {
 
   const values = parseList(parser_state);
 
-  return values
-    ? successTerm({
-        column: start_index + 1,
-        field_name,
-        kind: 'field_set',
-        operator,
-        values,
-      })
-    : failToken(parser_state);
+  if (!values) {
+    return failToken(parser_state);
+  }
+
+  if (!Array.isArray(values)) {
+    return values;
+  }
+
+  return successTerm({
+    column: start_index + 1,
+    field_name,
+    kind: 'field_set',
+    operator,
+    values,
+  });
 }
 
 /**
@@ -582,15 +601,23 @@ function parsePrefixTerm(parser_state, start_index, field_name) {
   }
 
   skipWhitespace(parser_state);
-  const value = parseBareValue(parser_state);
+  const value_result = parseResolvedBareValue(parser_state);
+
+  if (!value_result) {
+    return failToken(parser_state);
+  }
 
-  return value
+  if (!value_result.success) {
+    return value_result;
+  }
+
+  return value_result.value
     ? successTerm({
         column: start_index + 1,
         field_name,
         kind: 'field',
         operator: '^=',
-        value,
+        value: value_result.value,
       })
     : failToken(parser_state);
 }
@@ -607,15 +634,23 @@ function parseContainsTerm(parser_state, start_index, field_name) {
   }
 
   skipWhitespace(parser_state);
-  const value = parseBareValue(parser_state);
+  const value_result = parseResolvedBareValue(parser_state);
+
+  if (!value_result) {
+    return failToken(parser_state);
+  }
+
+  if (!value_result.success) {
+    return value_result;
+  }
 
-  return value
+  return value_result.value
     ? successTerm({
         column: start_index + 1,
         field_name,
         kind: 'field',
         operator: '~',
-        value,
+        value: value_result.value,
       })
     : failToken(parser_state);
 }
@@ -632,12 +667,18 @@ function parseEqualityTerm(parser_state, start_index, field_or_relation_name) {
   }
 
   skipWhitespace(parser_state);
-  const value = parseBareValue(parser_state);
+  const value_result = parseResolvedBareValue(parser_state);
 
-  if (!value) {
+  if (!value_result) {
     return failToken(parser_state);
   }
 
+  if (!value_result.success) {
+    return value_result;
+  }
+
+  const value = value_result.value;
+
   if (
     field_or_relation_name.startsWith('$') ||
     field_or_relation_name === 'title' ||
@@ -674,18 +715,22 @@ function parseFieldComparisonTerm(parser_state, start_index, field_name) {
   }
 
   skipWhitespace(parser_state);
-  const value = parseBareValue(parser_state);
+  const value_result = parseResolvedBareValue(parser_state);
 
-  if (!value) {
+  if (!value_result) {
     return failToken(parser_state);
   }
 
+  if (!value_result.success) {
+    return value_result;
+  }
+
   return successTerm({
     column: start_index + 1,
     field_name,
     kind: 'field',
     operator,
-    value,
+    value: value_result.value,
   });
 }
 
@@ -704,7 +749,7 @@ function parseFieldComparisonOperator(parser_state) {
 
 /**
  * @param {ParserState} parser_state
- * @returns {string[] | null}
+ * @returns {string[] | ParseFailureResult | null}
  */
 function parseList(parser_state) {
   if (!consumeOperator(parser_state, '[')) {
@@ -721,13 +766,17 @@ function parseList(parser_state) {
       return values.length > 0 ? values : null;
     }
 
-    const list_value = parseListValue(parser_state);
+    const list_value_result = parseResolvedListValue(parser_state);
 
-    if (!list_value) {
+    if (!list_value_result) {
       return null;
     }
 
-    values.push(list_value);
+    if (!list_value_result.success) {
+      return list_value_result;
+    }
+
+    values.push(list_value_result.value);
     skipWhitespace(parser_state);
 
     if (consumeOperator(parser_state, ']')) {
@@ -787,6 +836,76 @@ function parseListValue(parser_state) {
   return list_value?.trim() || null;
 }
 
+/**
+ * @param {ParserState} parser_state
+ * @returns {ParseValueResult | null}
+ */
+function parseResolvedBareValue(parser_state) {
+  const start_index = parser_state.index;
+  const raw_value = parseBareValue(parser_state);
+
+  if (!raw_value) {
+    return null;
+  }
+
+  return resolveBindingValue(parser_state, raw_value, start_index);
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @returns {ParseValueResult | null}
+ */
+function parseResolvedListValue(parser_state) {
+  const start_index = parser_state.index;
+  const raw_value = parseListValue(parser_state);
+
+  if (!raw_value) {
+    return null;
+  }
+
+  return resolveBindingValue(parser_state, raw_value, start_index);
+}
+
+/**
+ * @param {ParserState} parser_state
+ * @param {string} raw_value
+ * @param {number} start_index
+ * @returns {ParseValueResult}
+ */
+function resolveBindingValue(parser_state, raw_value, start_index) {
+  if (!raw_value.startsWith('@')) {
+    return {
+      success: true,
+      value: raw_value,
+    };
+  }
+
+  const binding_name = raw_value.slice(1);
+
+  if (!/^[a-z_][a-z0-9_]*$/u.test(binding_name)) {
+    return fail(
+      start_index + 1,
+      `Unsupported query binding "${raw_value}".`,
+      'query.invalid',
+    );
+  }
+
+  const binding_value = parser_state.bindings[binding_name];
+
+  if (binding_value === undefined) {
+    return fail(
+      start_index + 1,
+      `Missing query binding "${binding_name}".`,
+      'query.binding_missing',
+    );
+  }
+
+  return {
+    success: true,
+    value: binding_value,
+  };
+}
+
 /**
  * @param {ParserState} parser_state
  * @param {RegExp} pattern
@@ -918,12 +1037,13 @@ function failExpectedTerm(parser_state) {
 /**
  * @param {number} column
  * @param {string} message
+ * @param {string} code
  * @returns {{ diagnostic: PatramDiagnostic, success: false }}
  */
-function fail(column, message) {
+function fail(column, message, code = 'query.invalid') {
   return {
     diagnostic: {
-      code: 'query.invalid',
+      code,
       column,
       level: 'error',
       line: 1,

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

@@ -0,0 +1,63 @@
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+export type ParsedFieldName = string;
+export interface ParsedFieldTerm {
+    column: number;
+    field_name: ParsedFieldName;
+    kind: 'field';
+    operator: '!=' | '<' | '<=' | '=' | '>' | '>=' | '^=' | '~';
+    value: string;
+}
+export interface ParsedFieldSetTerm {
+    column: number;
+    field_name: ParsedFieldName;
+    kind: 'field_set';
+    operator: 'in' | 'not in';
+    values: string[];
+}
+export interface ParsedTraversalTerm {
+    column: number;
+    direction: 'in' | 'out';
+    relation_name: string;
+}
+export interface ParsedRelationTerm {
+    column: number;
+    kind: 'relation';
+    relation_name: string;
+}
+export interface ParsedRelationTargetTerm {
+    column: number;
+    kind: 'relation_target';
+    relation_name: string;
+    target_id: string;
+}
+export type ParsedAggregateComparison = '!=' | '<' | '<=' | '=' | '>' | '>=';
+export type ParsedAggregateName = 'any' | 'count' | 'none';
+export interface ParsedAggregateTerm {
+    aggregate_name: ParsedAggregateName;
+    comparison?: ParsedAggregateComparison;
+    expression: ParsedExpression;
+    kind: 'aggregate';
+    traversal: ParsedTraversalTerm;
+    value?: number;
+}
+export interface ParsedTermExpression {
+    kind: 'term';
+    term: ParsedTerm;
+}
+export interface ParsedNotExpression {
+    expression: ParsedExpression;
+    kind: 'not';
+}
+export interface ParsedBooleanExpression {
+    expressions: ParsedExpression[];
+    kind: 'and' | 'or';
+}
+export type ParsedTerm = ParsedAggregateTerm | ParsedFieldSetTerm | ParsedFieldTerm | ParsedRelationTargetTerm | ParsedRelationTerm;
+export type ParsedExpression = ParsedBooleanExpression | ParsedNotExpression | ParsedTermExpression;
+export type ParseWhereClauseResult = {
+    expression: ParsedExpression;
+    success: true;
+} | {
+    diagnostic: PatramDiagnostic;
+    success: false;
+};

package/lib/parse-yaml-claims.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Parse standalone YAML source into neutral directive claims.
+ *
+ * @param {ParseClaimsInput} parse_input
+ * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
+ * @returns {ParseSourceFileResult}
+ */
+export function parseYamlClaims(parse_input: ParseClaimsInput, parse_options?: {
+    multi_value_directive_names?: ReadonlySet<string>;
+}): ParseSourceFileResult;
+/**
+ * Parse YAML metadata into neutral directive fields.
+ *
+ * @param {{
+ *   file_path: string,
+ *   parser: 'markdown' | 'yaml',
+ *   source_text: string,
+ *   start_line: number,
+ *   markdown_style?: 'front_matter',
+ *   multi_value_directive_names?: ReadonlySet<string>,
+ * }} parse_input
+ * @returns {{ diagnostics: PatramDiagnostic[], directive_fields: PatramClaimFields[] }}
+ */
+export function parseYamlDirectiveFields(parse_input: {
+    file_path: string;
+    parser: "markdown" | "yaml";
+    source_text: string;
+    start_line: number;
+    markdown_style?: "front_matter";
+    multi_value_directive_names?: ReadonlySet<string>;
+}): {
+    diagnostics: PatramDiagnostic[];
+    directive_fields: PatramClaimFields[];
+};
+import type { ParseClaimsInput } from './parse-claims.types.ts';
+import type { ParseSourceFileResult } from './parse-claims.types.ts';
+import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { PatramClaimFields } from './parse-claims.types.ts';

package/lib/patram-config.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Parse and validate Patram JSON configuration.
+ *
+ * @param {unknown} config_json
+ * @returns {PatramGraphConfig}
+ */
+export function parsePatramConfig(config_json: unknown): PatramGraphConfig;
+/**
+ * @typedef {z.output<typeof class_definition_schema>} ClassDefinition
+ */
+export const class_definition_schema: z.ZodObject<{
+    builtin: z.ZodOptional<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof relation_definition_schema>} RelationDefinition
+ */
+export const relation_definition_schema: z.ZodObject<{
+    builtin: z.ZodOptional<z.ZodBoolean>;
+    from: z.ZodArray<z.ZodString>;
+    to: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof mapping_definition_schema>} MappingDefinition
+ */
+export const mapping_definition_schema: z.ZodObject<{
+    emit: z.ZodOptional<z.ZodObject<{
+        relation: z.ZodString;
+        target: z.ZodEnum<{
+            path: "path";
+            value: "value";
+        }>;
+        target_class: z.ZodString;
+    }, z.core.$strict>>;
+    node: z.ZodOptional<z.ZodObject<{
+        class: z.ZodString;
+        field: z.ZodString;
+        key: z.ZodOptional<z.ZodEnum<{
+            path: "path";
+            value: "value";
+        }>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof patramConfigSchema>} PatramGraphConfig
+ */
+export const patramConfigSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodURL>;
+    classes: z.ZodRecord<z.ZodString, z.ZodObject<{
+        builtin: z.ZodOptional<z.ZodBoolean>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    mappings: z.ZodRecord<z.ZodString, z.ZodObject<{
+        emit: z.ZodOptional<z.ZodObject<{
+            relation: z.ZodString;
+            target: z.ZodEnum<{
+                path: "path";
+                value: "value";
+            }>;
+            target_class: z.ZodString;
+        }, z.core.$strict>>;
+        node: z.ZodOptional<z.ZodObject<{
+            class: z.ZodString;
+            field: z.ZodString;
+            key: z.ZodOptional<z.ZodEnum<{
+                path: "path";
+                value: "value";
+            }>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    relations: z.ZodRecord<z.ZodString, z.ZodObject<{
+        builtin: z.ZodOptional<z.ZodBoolean>;
+        from: z.ZodArray<z.ZodString>;
+        to: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ClassDefinition = z.output<typeof class_definition_schema>;
+export type RelationDefinition = z.output<typeof relation_definition_schema>;
+export type MappingNodeDefinition = z.output<typeof mapping_node_schema>;
+export type MappingEmitDefinition = z.output<typeof mapping_emit_schema>;
+export type MappingDefinition = z.output<typeof mapping_definition_schema>;
+export type PatramGraphConfig = z.output<typeof patramConfigSchema>;
+import { z } from 'zod';
+/**
+ * @typedef {z.output<typeof mapping_node_schema>} MappingNodeDefinition
+ */
+declare const mapping_node_schema: z.ZodObject<{
+    class: z.ZodString;
+    field: z.ZodString;
+    key: z.ZodOptional<z.ZodEnum<{
+        path: "path";
+        value: "value";
+    }>>;
+}, z.core.$strict>;
+/**
+ * @typedef {z.output<typeof mapping_emit_schema>} MappingEmitDefinition
+ */
+declare const mapping_emit_schema: z.ZodObject<{
+    relation: z.ZodString;
+    target: z.ZodEnum<{
+        path: "path";
+        value: "value";
+    }>;
+    target_class: z.ZodString;
+}, z.core.$strict>;
+export {};

package/lib/patram-config.types.d.ts

@@ -0,0 +1,14 @@
+import type { ClassSchemaConfig, MetadataFieldConfig } from './load-patram-config.types.ts';
+export type ClassDefinition = import('./patram-config.js').ClassDefinition;
+export type RelationDefinition = import('./patram-config.js').RelationDefinition;
+export type MappingNodeDefinition = import('./patram-config.js').MappingNodeDefinition;
+export type MappingEmitDefinition = import('./patram-config.js').MappingEmitDefinition;
+export type MappingDefinition = import('./patram-config.js').MappingDefinition;
+export type PatramGraphConfig = import('./patram-config.js').PatramGraphConfig;
+export type PatramClassConfig = ClassDefinition & {
+    schema?: ClassSchemaConfig;
+};
+export type PatramConfig = Omit<PatramGraphConfig, 'classes'> & {
+    classes: Record<string, PatramClassConfig>;
+    fields?: Record<string, MetadataFieldConfig>;
+};

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