patram 0.3.0 → 0.5.0

package/lib/check-directive-value.js

@@ -21,6 +21,7 @@ import {
  * @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[]}
  */
@@ -31,6 +32,7 @@ export function checkDirectiveValue(
   repo_config,
   _directive_rule,
   document_entity_keys,
+  document_node_references,
   document_paths,
 ) {
   const mapping_definition = resolveDirectiveMapping(mappings, claim);
@@ -79,6 +81,7 @@ export function checkDirectiveValue(
     repo_config,
     type_definition,
     document_entity_keys,
+    document_node_references,
     document_paths,
   );
 }
@@ -157,6 +160,7 @@ function createInvalidTypeDiagnostic(
  * @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[]}
  */
@@ -167,6 +171,7 @@ function createPathClassDiagnostics(
   repo_config,
   type_definition,
   document_entity_keys,
+  document_node_references,
   document_paths,
 ) {
   if (
@@ -177,6 +182,7 @@ function createPathClassDiagnostics(
       claim,
       type_definition.path_class,
       document_entity_keys,
+      document_node_references,
       document_paths,
       repo_config,
     )
@@ -198,6 +204,7 @@ function createPathClassDiagnostics(
  * @param {PatramClaim} claim
  * @param {string} path_class_name
  * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
  * @param {Set<string>} document_paths
  * @param {PatramRepoConfig} repo_config
  * @returns {boolean}
@@ -207,6 +214,7 @@ function isDirectivePathInClass(
   claim,
   path_class_name,
   document_entity_keys,
+  document_node_references,
   document_paths,
   repo_config,
 ) {
@@ -223,6 +231,7 @@ function isDirectivePathInClass(
     'path',
     claim,
     document_entity_keys,
+    document_node_references,
     document_paths,
   );
 

package/lib/check-graph.js

@@ -118,14 +118,13 @@ function collectBrokenLinkDiagnostics(
   target_node,
   existing_file_path_set,
 ) {
-  const target_class = target_node.$class ?? target_node.kind;
   const target_path = target_node.$path ?? target_node.path;
 
   if (graph_edge.relation !== 'links_to') {
     return;
   }
 
-  if (target_class !== 'document' || !target_path) {
+  if (!target_path) {
     return;
   }
 

package/lib/cli-help-metadata.js

@@ -280,6 +280,8 @@ const HELP_TOPIC_DEFINITIONS = {
   'query-language': {
     examples: [
       '$class=decision and status=accepted',
+      '$class=task or status=done',
+      '($class=task or status=blocked) and title~Show',
       '$path^=docs/plans/',
       'title~query',
       'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md',
@@ -320,6 +322,14 @@ const HELP_TOPIC_DEFINITIONS = {
         description: 'Combine terms',
         label: 'and',
       },
+      {
+        description: 'Match either side',
+        label: 'or',
+      },
+      {
+        description: 'Group boolean expressions',
+        label: '( )',
+      },
       {
         description: 'Count comparisons',
         label: '!= < > >= <=',
@@ -363,6 +373,8 @@ const HELP_TOPIC_DEFINITIONS = {
       'count(<traversal>, <term> and <term>) <comparison> <number>',
       'not <term>',
       '<term> and <term>',
+      '<term> or <term>',
+      '(<expression>)',
     ],
   },
 };

package/lib/command-output.js

@@ -45,6 +45,20 @@ export async function writeCommandOutput(
     parsed_command,
   );
 
+  await writeRenderedCommandOutput(io_context, parsed_command, rendered_output);
+}
+
+/**
+ * @param {{ stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @param {ParsedCliArguments} parsed_command
+ * @param {string} rendered_output
+ * @returns {Promise<void>}
+ */
+export async function writeRenderedCommandOutput(
+  io_context,
+  parsed_command,
+  rendered_output,
+) {
   if (shouldPageCommandOutput(parsed_command, io_context.stdout)) {
     await writeInteractiveOutput(io_context, rendered_output);
 
@@ -62,7 +76,8 @@ export async function writeCommandOutput(
 export function shouldPageCommandOutput(parsed_command, output_stream) {
   return (
     output_stream.isTTY === true &&
-    (parsed_command.command_name === 'query' ||
+    (parsed_command.command_name === 'fields' ||
+      parsed_command.command_name === 'query' ||
       parsed_command.command_name === 'show')
   );
 }

package/lib/discover-fields.js

@@ -63,9 +63,14 @@ const PATH_PATTERN = /^[a-z0-9_.-]+\.[a-z0-9]+$/du;
  * Discover likely field schema from source files.
  *
  * @param {string} [project_directory]
+ * @param {{ defined_field_names?: ReadonlySet<string> }} [options]
  * @returns {Promise<FieldDiscoveryResult>}
  */
-export async function discoverFields(project_directory = process.cwd()) {
+export async function discoverFields(
+  project_directory = process.cwd(),
+  options,
+) {
+  const defined_field_names = options?.defined_field_names ?? new Set();
   const source_file_paths = await listSourceFiles(
     DEFAULT_INCLUDE_PATTERNS,
     project_directory,
@@ -140,6 +145,9 @@ export async function discoverFields(project_directory = process.cwd()) {
   );
   const fields = [...field_buckets.values()]
     .map(buildFieldSuggestion)
+    .filter(
+      (field_suggestion) => !defined_field_names.has(field_suggestion.name),
+    )
     .sort((left_suggestion, right_suggestion) =>
       left_suggestion.confidence !== right_suggestion.confidence
         ? right_suggestion.confidence - left_suggestion.confidence

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/layout-stored-queries.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 /**
  * @import { OutputStoredQueryItem } from './output-view.types.ts';
  */
@@ -91,33 +92,141 @@ 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 {import('./parse-where-clause.types.ts').ParsedClause} 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;
 }
 
 /**
@@ -182,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: ')' },
   ];
 
@@ -208,22 +317,6 @@ function createTraversalSegments(traversal) {
   ];
 }
 
-/**
- * @param {import('./parse-where-clause.types.ts').ParsedClause[]} clauses
- * @returns {StoredQuerySegment[]}
- */
-function createNestedClauseSegments(clauses) {
-  return clauses.flatMap((clause, clause_index) => {
-    const clause_phrase = createClausePhrase(clause, clause_index > 0);
-
-    if (clause_index === 0) {
-      return clause_phrase;
-    }
-
-    return [{ kind: 'plain', text: ' ' }, ...clause_phrase];
-  });
-}
-
 /**
  * @param {string[]} values
  * @returns {StoredQuerySegment[]}