patram 0.2.0 → 0.4.0

package/lib/document-node-identity.js

@@ -0,0 +1,317 @@
+/**
+ * @import { PatramClaim } from './parse-claims.types.ts';
+ * @import { MappingDefinition } from './patram-config.types.ts';
+ */
+
+import { posix } from 'node:path';
+
+/**
+ * @typedef {{
+ *   class_name: string,
+ *   id: string,
+ *   key: string,
+ *   path: string,
+ * }} DocumentNodeReference
+ */
+
+/**
+ * Collect semantic entity keys defined by canonical documents.
+ *
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramClaim[]} claims
+ * @returns {Map<string, string>}
+ */
+export function collectDocumentEntityKeys(mappings, claims) {
+  /** @type {Map<string, string>} */
+  const document_entity_keys = new Map();
+
+  for (const claim of claims) {
+    const mapping_definition = resolveMappingDefinition(mappings, claim);
+
+    if (
+      mapping_definition?.node?.key !== 'value' ||
+      mapping_definition.node.class === 'document'
+    ) {
+      continue;
+    }
+
+    const source_path = normalizeRepoRelativePath(claim.origin.path);
+    const entity_map_key = getDocumentEntityMapKey(
+      source_path,
+      mapping_definition.node.class,
+    );
+    const entity_key = getStringClaimValue(claim);
+    const existing_entity_key = document_entity_keys.get(entity_map_key);
+
+    if (existing_entity_key && existing_entity_key !== entity_key) {
+      throw new Error(
+        `Document "${source_path}" defines multiple ${mapping_definition.node.class} ids.`,
+      );
+    }
+
+    document_entity_keys.set(entity_map_key, entity_key);
+  }
+
+  return document_entity_keys;
+}
+
+/**
+ * Collect canonical graph identities for document-backed source paths.
+ *
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramClaim[]} claims
+ * @returns {Map<string, DocumentNodeReference>}
+ */
+export function collectDocumentNodeReferences(mappings, claims) {
+  /** @type {Map<string, DocumentNodeReference>} */
+  const document_node_references = new Map();
+  /** @type {Map<string, string>} */
+  const pending_document_keys = new Map();
+
+  for (const claim of claims) {
+    const source_path = normalizeRepoRelativePath(claim.origin.path);
+    const document_node_reference =
+      document_node_references.get(source_path) ??
+      createDefaultDocumentNodeReference(source_path);
+    const mapping_definition = resolveMappingDefinition(mappings, claim);
+
+    document_node_references.set(source_path, document_node_reference);
+
+    if (mapping_definition?.node?.class !== 'document') {
+      continue;
+    }
+
+    applyDocumentNodeMapping(
+      document_node_reference,
+      mapping_definition.node,
+      claim,
+      pending_document_keys,
+      source_path,
+    );
+  }
+
+  return document_node_references;
+}
+
+/**
+ * Resolve the canonical node id for a source document path.
+ *
+ * @param {Record<string, string> | undefined} document_node_ids
+ * @param {string} document_path
+ * @returns {string}
+ */
+export function resolveDocumentNodeId(document_node_ids, document_path) {
+  return document_node_ids?.[document_path] ?? `doc:${document_path}`;
+}
+
+/**
+ * Normalize one repo-relative source path.
+ *
+ * @param {string} source_path
+ * @returns {string}
+ */
+export function normalizeRepoRelativePath(source_path) {
+  return posix.normalize(source_path.replaceAll('\\', '/'));
+}
+
+/**
+ * @param {DocumentNodeReference} document_node_reference
+ * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
+ * @param {PatramClaim} claim
+ * @param {Map<string, string>} pending_document_keys
+ * @param {string} source_path
+ */
+function applyDocumentNodeMapping(
+  document_node_reference,
+  node_mapping,
+  claim,
+  pending_document_keys,
+  source_path,
+) {
+  if (node_mapping.field === '$class') {
+    assignDocumentNodeClass(
+      document_node_reference,
+      getStringClaimValue(claim),
+    );
+    applyPendingDocumentKey(
+      document_node_reference,
+      pending_document_keys,
+      source_path,
+    );
+    return;
+  }
+
+  if (node_mapping.field !== '$id' || node_mapping.key !== 'value') {
+    return;
+  }
+
+  const document_node_key = getStringClaimValue(claim);
+
+  if (document_node_reference.class_name === 'document') {
+    assignPendingDocumentKey(
+      pending_document_keys,
+      source_path,
+      document_node_key,
+    );
+    return;
+  }
+
+  assignDocumentNodeKey(document_node_reference, document_node_key);
+}
+
+/**
+ * @param {DocumentNodeReference} document_node_reference
+ * @param {Map<string, string>} pending_document_keys
+ * @param {string} source_path
+ */
+function applyPendingDocumentKey(
+  document_node_reference,
+  pending_document_keys,
+  source_path,
+) {
+  if (document_node_reference.class_name === 'document') {
+    return;
+  }
+
+  const pending_document_key = pending_document_keys.get(source_path);
+
+  if (!pending_document_key) {
+    return;
+  }
+
+  assignDocumentNodeKey(document_node_reference, pending_document_key);
+}
+
+/**
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramClaim} claim
+ * @returns {MappingDefinition | null}
+ */
+function resolveMappingDefinition(mappings, claim) {
+  if (claim.type === 'directive') {
+    return resolveDirectiveMapping(mappings, claim);
+  }
+
+  return mappings[claim.type] ?? null;
+}
+
+/**
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramClaim} claim
+ * @returns {MappingDefinition | null}
+ */
+function resolveDirectiveMapping(mappings, claim) {
+  if (!claim.parser || !claim.name) {
+    return null;
+  }
+
+  return mappings[`${claim.parser}.directive.${claim.name}`] ?? null;
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @returns {string}
+ */
+function getStringClaimValue(claim) {
+  if (typeof claim.value === 'string') {
+    return claim.value;
+  }
+
+  throw new Error(`Claim "${claim.id}" does not carry a string value.`);
+}
+
+/**
+ * @param {string} document_path
+ * @param {string} class_name
+ * @returns {string}
+ */
+function getDocumentEntityMapKey(document_path, class_name) {
+  return `${class_name}:${document_path}`;
+}
+
+/**
+ * @param {string} source_path
+ * @returns {DocumentNodeReference}
+ */
+function createDefaultDocumentNodeReference(source_path) {
+  return {
+    class_name: 'document',
+    id: `doc:${source_path}`,
+    key: source_path,
+    path: source_path,
+  };
+}
+
+/**
+ * @param {DocumentNodeReference} document_node_reference
+ * @param {string} class_name
+ */
+function assignDocumentNodeClass(document_node_reference, class_name) {
+  if (
+    document_node_reference.class_name !== 'document' &&
+    document_node_reference.class_name !== class_name
+  ) {
+    throw new Error(
+      `Document "${document_node_reference.path}" defines multiple semantic classes.`,
+    );
+  }
+
+  document_node_reference.class_name = class_name;
+  document_node_reference.id = getNodeId(
+    document_node_reference.class_name,
+    document_node_reference.key,
+  );
+}
+
+/**
+ * @param {DocumentNodeReference} document_node_reference
+ * @param {string} node_key
+ */
+function assignDocumentNodeKey(document_node_reference, node_key) {
+  if (
+    document_node_reference.key !== document_node_reference.path &&
+    document_node_reference.key !== node_key
+  ) {
+    throw new Error(
+      `Document "${document_node_reference.path}" defines multiple semantic ids.`,
+    );
+  }
+
+  document_node_reference.key = node_key;
+  document_node_reference.id = getNodeId(
+    document_node_reference.class_name,
+    document_node_reference.key,
+  );
+}
+
+/**
+ * @param {Map<string, string>} pending_document_keys
+ * @param {string} source_path
+ * @param {string} node_key
+ */
+function assignPendingDocumentKey(
+  pending_document_keys,
+  source_path,
+  node_key,
+) {
+  const existing_node_key = pending_document_keys.get(source_path);
+
+  if (existing_node_key && existing_node_key !== node_key) {
+    throw new Error(`Document "${source_path}" defines multiple semantic ids.`);
+  }
+
+  pending_document_keys.set(source_path, node_key);
+}
+
+/**
+ * @param {string} class_name
+ * @param {string} node_key
+ * @returns {string}
+ */
+function getNodeId(class_name, node_key) {
+  if (class_name === 'document') {
+    return `doc:${node_key}`;
+  }
+
+  return `${class_name}:${node_key}`;
+}

package/lib/format-node-header.js

@@ -3,17 +3,19 @@
  * @returns {string}
  */
 export function formatNodeHeader(output_item) {
-  if (isDocumentNode(output_item)) {
-    return `document ${output_item.path}`;
+  if (output_item.path) {
+    return `${output_item.node_kind} ${output_item.path}`;
   }
 
-  return `${output_item.node_kind} ${output_item.id}`;
+  return `${output_item.node_kind} ${getOutputNodeKey(output_item.id)}`;
 }
 
 /**
- * @param {import('./output-view.types.ts').OutputNodeItem} output_item
- * @returns {boolean}
+ * @param {string} node_id
+ * @returns {string}
  */
-export function isDocumentNode(output_item) {
-  return output_item.id === `doc:${output_item.path}`;
+function getOutputNodeKey(node_id) {
+  return node_id.includes(':')
+    ? node_id.split(':').slice(1).join(':')
+    : node_id;
 }

package/lib/format-output-metadata.js

@@ -1,5 +1,4 @@
 import { formatDerivedSummaryRow } from './format-derived-summary-row.js';
-import { isDocumentNode } from './format-node-header.js';
 
 /**
  * @param {import('./output-view.types.ts').OutputNodeItem} output_item
@@ -8,18 +7,8 @@ import { isDocumentNode } from './format-node-header.js';
 export function formatOutputNodeMetadataRows(output_item) {
   /** @type {string[]} */
   const metadata_rows = [];
-  /** @type {string[]} */
-  const stored_metadata_fields = [];
-
-  if (isDocumentNode(output_item)) {
-    stored_metadata_fields.push(`kind: ${output_item.node_kind}`);
-  } else {
-    stored_metadata_fields.push(`path: ${output_item.path}`);
-  }
-
-  if (output_item.status) {
-    stored_metadata_fields.push(`status: ${output_item.status}`);
-  }
+  const stored_metadata_fields =
+    output_item.visible_fields.map(formatMetadataField);
 
   if (stored_metadata_fields.length > 0) {
     metadata_rows.push(stored_metadata_fields.join('  '));
@@ -39,16 +28,7 @@ export function formatOutputNodeMetadataRows(output_item) {
 export function formatResolvedLinkMetadataRows(target) {
   /** @type {string[]} */
   const metadata_rows = [];
-  /** @type {string[]} */
-  const stored_metadata_fields = [];
-
-  if (target.kind) {
-    stored_metadata_fields.push(`kind: ${target.kind}`);
-  }
-
-  if (target.status) {
-    stored_metadata_fields.push(`status: ${target.status}`);
-  }
+  const stored_metadata_fields = target.visible_fields.map(formatMetadataField);
 
   if (stored_metadata_fields.length > 0) {
     metadata_rows.push(stored_metadata_fields.join('  '));
@@ -60,3 +40,15 @@ export function formatResolvedLinkMetadataRows(target) {
 
   return metadata_rows;
 }
+
+/**
+ * @param {import('./output-view.types.ts').OutputMetadataField} output_field
+ * @returns {string}
+ */
+function formatMetadataField(output_field) {
+  const value = Array.isArray(output_field.value)
+    ? output_field.value.join(', ')
+    : output_field.value;
+
+  return `${output_field.name}: ${value}`;
+}

package/lib/layout-stored-queries.js

@@ -92,65 +92,145 @@ function createStoredQueryPhrases(where_clause) {
     return createFallbackPhrases(where_clause);
   }
 
-  return parse_result.clauses.map((clause, clause_index) =>
-    createClausePhrase(clause, clause_index > 0),
+  return createExpressionPhrases(parse_result.expression);
+}
+
+/**
+ * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @returns {StoredQuerySegment[][]}
+ */
+function createExpressionPhrases(expression) {
+  if (expression.kind !== 'and' && expression.kind !== 'or') {
+    return [[...createExpressionSegments(expression, 0)]];
+  }
+
+  return expression.expressions.map((subexpression, expression_index) =>
+    createExpressionPhrase(
+      subexpression,
+      expression.kind,
+      expression_index > 0,
+    ),
   );
 }
 
 /**
- * @param {{
- *   is_negated: boolean,
- *   term:
- *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }
- *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }
- *     | { kind: 'relation', relation_name: string }
- *     | { kind: 'relation_target', relation_name: string, target_id: string }
- *     | {
- *         aggregate_name: 'any' | 'count' | 'none',
- *         clauses: unknown[],
- *         comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
- *         kind: 'aggregate',
- *         traversal: { direction: 'in' | 'out', relation_name: string },
- *         value?: number,
- *       },
- * }} clause
- * @param {boolean} should_prefix_and
+ * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {'and' | 'or'} operator
+ * @param {boolean} should_prefix_operator
  * @returns {StoredQuerySegment[]}
  */
-function createClausePhrase(clause, should_prefix_and) {
+function createExpressionPhrase(expression, operator, should_prefix_operator) {
   /** @type {StoredQuerySegment[]} */
   const phrase = [];
 
-  if (should_prefix_and) {
-    phrase.push({ kind: 'keyword', text: 'and' });
+  if (should_prefix_operator) {
+    phrase.push({ kind: 'keyword', text: operator });
     phrase.push({ kind: 'plain', text: ' ' });
   }
 
-  if (clause.is_negated) {
-    phrase.push({ kind: 'keyword', text: 'not' });
-    phrase.push({ kind: 'plain', text: ' ' });
+  phrase.push(
+    ...createExpressionSegments(
+      expression,
+      getBooleanExpressionPrecedence(operator),
+    ),
+  );
+
+  return phrase;
+}
+
+/**
+ * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @param {number} parent_precedence
+ * @returns {StoredQuerySegment[]}
+ */
+function createExpressionSegments(expression, parent_precedence) {
+  const expression_precedence = getExpressionPrecedence(expression);
+  const expression_segments = createRawExpressionSegments(expression);
+
+  if (expression_precedence >= parent_precedence) {
+    return expression_segments;
   }
 
-  phrase.push(...createTermSegments(clause.term));
+  return [
+    { kind: 'operator', text: '(' },
+    ...expression_segments,
+    { kind: 'operator', text: ')' },
+  ];
+}
 
-  return phrase;
+/**
+ * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @returns {StoredQuerySegment[]}
+ */
+function createRawExpressionSegments(expression) {
+  if (expression.kind === 'and' || expression.kind === 'or') {
+    return expression.expressions.flatMap((subexpression, expression_index) => {
+      const subexpression_segments = createExpressionSegments(
+        subexpression,
+        getExpressionPrecedence(expression),
+      );
+
+      if (expression_index === 0) {
+        return subexpression_segments;
+      }
+
+      return [
+        { kind: 'plain', text: ' ' },
+        { kind: 'keyword', text: expression.kind },
+        { kind: 'plain', text: ' ' },
+        ...subexpression_segments,
+      ];
+    });
+  }
+
+  if (expression.kind === 'not') {
+    return [
+      { kind: 'keyword', text: 'not' },
+      { kind: 'plain', text: ' ' },
+      ...createExpressionSegments(
+        expression.expression,
+        getExpressionPrecedence(expression),
+      ),
+    ];
+  }
+
+  if (expression.kind === 'term') {
+    return createTermSegments(expression.term);
+  }
+
+  throw new Error('Unsupported stored-query expression.');
+}
+
+/**
+ * @param {import('./parse-where-clause.types.ts').ParsedExpression} expression
+ * @returns {number}
+ */
+function getExpressionPrecedence(expression) {
+  if (expression.kind === 'or') {
+    return 1;
+  }
+
+  if (expression.kind === 'and') {
+    return 2;
+  }
+
+  if (expression.kind === 'not') {
+    return 3;
+  }
+
+  return 4;
+}
+
+/**
+ * @param {'and' | 'or'} operator
+ * @returns {number}
+ */
+function getBooleanExpressionPrecedence(operator) {
+  return operator === 'or' ? 1 : 2;
 }
 
 /**
- * @param {
- *   | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }
- *   | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }
- *   | { kind: 'relation', relation_name: string }
- *   | { kind: 'relation_target', relation_name: string, target_id: string }
- *   | {
- *       aggregate_name: 'any' | 'count' | 'none',
- *       clauses: { is_negated: boolean, term: unknown }[],
- *       comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
- *       kind: 'aggregate',
- *       traversal: { direction: 'in' | 'out', relation_name: string },
- *       value?: number,
- *     }
- * } term
+ * @param {import('./parse-where-clause.types.ts').ParsedTerm} term
  * @returns {StoredQuerySegment[]}
  */
 function createTermSegments(term) {
@@ -185,7 +265,7 @@ function createTermSegments(term) {
 }
 
 /**
- * @param {{ field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }} term
+ * @param {import('./parse-where-clause.types.ts').ParsedFieldSetTerm} term
  * @returns {StoredQuerySegment[]}
  */
 function createFieldSetSegments(term) {
@@ -201,14 +281,7 @@ function createFieldSetSegments(term) {
 }
 
 /**
- * @param {{
- *   aggregate_name: 'any' | 'count' | 'none',
- *   clauses: { is_negated: boolean, term: unknown }[],
- *   comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
- *   kind: 'aggregate',
- *   traversal: { direction: 'in' | 'out', relation_name: string },
- *   value?: number,
- * }} term
+ * @param {import('./parse-where-clause.types.ts').ParsedAggregateTerm} term
  * @returns {StoredQuerySegment[]}
  */
 function createAggregateSegments(term) {
@@ -218,7 +291,7 @@ function createAggregateSegments(term) {
     { kind: 'operator', text: '(' },
     ...createTraversalSegments(term.traversal),
     { kind: 'operator', text: ', ' },
-    ...createNestedClauseSegments(term.clauses),
+    ...createExpressionSegments(term.expression, 0),
     { kind: 'operator', text: ')' },
   ];
 
@@ -244,40 +317,6 @@ function createTraversalSegments(traversal) {
   ];
 }
 
-/**
- * @param {{ is_negated: boolean, term: unknown }[]} clauses
- * @returns {StoredQuerySegment[]}
- */
-function createNestedClauseSegments(clauses) {
-  return clauses.flatMap((clause, clause_index) => {
-    const clause_phrase = createClausePhrase(
-      /** @type {{
-       *   is_negated: boolean,
-       *   term:
-       *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }
-       *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }
-       *     | { kind: 'relation', relation_name: string }
-       *     | { kind: 'relation_target', relation_name: string, target_id: string }
-       *     | {
-       *         aggregate_name: 'any' | 'count' | 'none',
-       *         clauses: { is_negated: boolean, term: unknown }[],
-       *         comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
-       *         kind: 'aggregate',
-       *         traversal: { direction: 'in' | 'out', relation_name: string },
-       *         value?: number,
-       *       },
-       * }} */ (clause),
-      clause_index > 0,
-    );
-
-    if (clause_index === 0) {
-      return clause_phrase;
-    }
-
-    return [{ kind: 'plain', text: ' ' }, ...clause_phrase];
-  });
-}
-
 /**
  * @param {string[]} values
  * @returns {StoredQuerySegment[]}