patram 0.11.0 → 0.12.0

package/lib/output/view-model/index.js

@@ -1,19 +1,24 @@
 /**
  * @import { BuildGraphResult, GraphNode } from '../../graph/build-graph.types.ts';
- * @import { DerivedSummaryEvaluator } from '../derived-summary.js';
  * @import { PatramRepoConfig } from '../../config/load-patram-config.types.ts';
- * @import { OutputDerivedSummary, OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, RefsOutputView, ShowOutputView } from '../output-view.types.ts';
+ * @import { OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, RefsOutputView, ShowOutputView } from '../output-view.types.ts';
  */
 /* eslint-disable max-lines */
 
 import { resolveDocumentNodeId } from '../../graph/build-graph-identity.js';
+import {
+  getGraphNodeClassName,
+  getGraphNodeId,
+  getGraphNodeMetadataValue,
+  getGraphNodePath,
+} from '../../graph/graph-node.js';
 
 /**
  * Create a shared output view from one command result.
  *
  * @param {'query' | 'queries'} command_name
  * @param {GraphNode[] | { name: string, where: string, description?: string }[]} command_items
- * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, hints?: string[], limit?: number, offset?: number, repo_config?: PatramRepoConfig, total_count?: number }=} command_options
+ * @param {{ hints?: string[], limit?: number, offset?: number, repo_config?: PatramRepoConfig, total_count?: number }=} command_options
  * @returns {OutputView}
  */
 export function createOutputView(command_name, command_items, command_options) {
@@ -37,7 +42,7 @@ export function createOutputView(command_name, command_items, command_options) {
  * Create a shared output view for the show command.
  *
  * @param {{ incoming_summary: Record<string, number>, path: string, rendered_source: string, resolved_links: Array<{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }>, source: string }} show_output
- * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, document_node_ids?: BuildGraphResult['document_node_ids'], graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }=} command_options
+ * @param {{ document_path_ids?: BuildGraphResult['document_path_ids'], graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }=} command_options
  * @returns {ShowOutputView}
  */
 export function createShowOutputView(show_output, command_options = {}) {
@@ -62,7 +67,7 @@ export function createShowOutputView(show_output, command_options = {}) {
  * Create a shared output view for the refs command.
  *
  * @param {{ incoming: Record<string, GraphNode[]>, node: GraphNode }} refs_output
- * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, repo_config?: PatramRepoConfig }=} command_options
+ * @param {{ repo_config?: PatramRepoConfig }=} command_options
  * @returns {RefsOutputView}
  */
 export function createRefsOutputView(refs_output, command_options = {}) {
@@ -74,8 +79,6 @@ export function createRefsOutputView(refs_output, command_options = {}) {
       (graph_node) =>
         createOutputNodeItem(
           graph_node,
-          command_options.derived_summary_evaluator?.evaluate(graph_node) ??
-            null,
           command_options.repo_config?.fields ?? {},
         ),
     );
@@ -87,8 +90,6 @@ export function createRefsOutputView(refs_output, command_options = {}) {
     incoming,
     node: createOutputNodeItem(
       refs_output.node,
-      command_options.derived_summary_evaluator?.evaluate(refs_output.node) ??
-        null,
       command_options.repo_config?.fields ?? {},
     ),
     summary: {
@@ -100,7 +101,7 @@ export function createRefsOutputView(refs_output, command_options = {}) {
 
 /**
  * @param {GraphNode[]} graph_nodes
- * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, hints?: string[], limit?: number, offset?: number, repo_config?: PatramRepoConfig, total_count?: number }=} command_options
+ * @param {{ hints?: string[], limit?: number, offset?: number, repo_config?: PatramRepoConfig, total_count?: number }=} command_options
  * @returns {OutputView}
  */
 function createQueryOutputView(graph_nodes, command_options = {}) {
@@ -110,11 +111,12 @@ function createQueryOutputView(graph_nodes, command_options = {}) {
     command: 'query',
     hints:
       command_options.hints ??
-      (total_count === 0 ? ["Try: patram query --where '$class=task'"] : []),
+      (total_count === 0
+        ? ['Try: patram query --cypher "MATCH (n:Task) RETURN n"']
+        : []),
     items: graph_nodes.map((graph_node) =>
       createOutputNodeItem(
         graph_node,
-        command_options.derived_summary_evaluator?.evaluate(graph_node) ?? null,
         command_options.repo_config?.fields ?? {},
       ),
     ),
@@ -166,11 +168,13 @@ function countIncomingReferenceItems(incoming) {
 
 /**
  * @param {GraphNode} graph_node
- * @param {OutputDerivedSummary | null} derived_summary
  * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
  * @returns {OutputNodeItem}
  */
-function createOutputNodeItem(graph_node, derived_summary, field_definitions) {
+function createOutputNodeItem(graph_node, field_definitions) {
+  const description = getScalarGraphNodeField(
+    getGraphNodeMetadataValue(graph_node, 'description'),
+  );
   const title = getOutputNodeTitle(graph_node);
   const path = getOutputNodePath(graph_node);
   const node_class = getOutputNodeClass(graph_node);
@@ -179,12 +183,12 @@ function createOutputNodeItem(graph_node, derived_summary, field_definitions) {
 
   if (!title || !node_class) {
     throw new Error(
-      `Expected graph node "${graph_node.id}" to have a title and path.`,
+      `Expected graph node "${getOutputNodeId(graph_node)}" to have a title and path.`,
     );
   }
 
-  return {
-    derived_summary: derived_summary ?? undefined,
+  /** @type {OutputNodeItem} */
+  const output_item = {
     fields,
     id: getOutputNodeId(graph_node),
     kind: 'node',
@@ -193,21 +197,54 @@ function createOutputNodeItem(graph_node, derived_summary, field_definitions) {
     title,
     visible_fields,
   };
+
+  if (description) {
+    output_item.description = description;
+  }
+
+  return output_item;
 }
 
 /**
  * @param {{ kind?: string, path: string, status?: string, title: string }} target
  * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
- * @param {OutputDerivedSummary | null} derived_summary
  * @param {GraphNode | undefined} graph_node
  * @returns {OutputResolvedLinkTarget}
  */
-function createResolvedLinkTarget(
-  target,
-  field_definitions,
-  derived_summary,
-  graph_node,
-) {
+function createResolvedLinkTarget(target, field_definitions, graph_node) {
+  const description = getScalarGraphNodeField(
+    graph_node
+      ? getGraphNodeMetadataValue(graph_node, 'description')
+      : undefined,
+  );
+  const fields = collectResolvedLinkFields(
+    target,
+    field_definitions,
+    graph_node,
+  );
+
+  return {
+    description,
+    fields,
+    id: graph_node ? getOutputNodeId(graph_node) : `doc:${target.path}`,
+    kind: resolveResolvedLinkKind(target, graph_node),
+    path: resolveResolvedLinkPath(target, graph_node),
+    title: resolveResolvedLinkTitle(target, graph_node),
+    visible_fields: createVisibleOutputFields(fields, field_definitions),
+  };
+}
+
+/**
+ * @param {{ kind?: string, path: string, status?: string, title: string }} target
+ * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
+ * @param {GraphNode | undefined} graph_node
+ * @returns {Record<string, string | string[]>}
+ */
+function collectResolvedLinkFields(target, field_definitions, graph_node) {
+  if (graph_node) {
+    return collectOutputFields(graph_node, field_definitions);
+  }
+
   /** @type {Record<string, string | string[]>} */
   const fields = {};
 
@@ -215,18 +252,34 @@ function createResolvedLinkTarget(
     fields.status = target.status;
   }
 
-  /** @type {OutputResolvedLinkTarget} */
-  const resolved_target = {
-    derived_summary: derived_summary ?? undefined,
-    fields,
-    id: graph_node ? getOutputNodeId(graph_node) : `doc:${target.path}`,
-    kind: target.kind ?? 'document',
-    path: target.path,
-    title: target.title,
-    visible_fields: createVisibleOutputFields(fields, field_definitions),
-  };
+  return fields;
+}
+
+/**
+ * @param {{ kind?: string, path: string, status?: string, title: string }} target
+ * @param {GraphNode | undefined} graph_node
+ * @returns {string}
+ */
+function resolveResolvedLinkKind(target, graph_node) {
+  return getOutputNodeClass(graph_node) ?? target.kind ?? 'document';
+}
+
+/**
+ * @param {{ kind?: string, path: string, status?: string, title: string }} target
+ * @param {GraphNode | undefined} graph_node
+ * @returns {string}
+ */
+function resolveResolvedLinkPath(target, graph_node) {
+  return getOutputNodePath(graph_node) ?? target.path;
+}
 
-  return resolved_target;
+/**
+ * @param {{ kind?: string, path: string, status?: string, title: string }} target
+ * @param {GraphNode | undefined} graph_node
+ * @returns {string}
+ */
+function resolveResolvedLinkTitle(target, graph_node) {
+  return getOutputNodeTitle(graph_node) ?? target.title;
 }
 
 /**
@@ -242,32 +295,43 @@ function getScalarGraphNodeField(field_value) {
 }
 
 /**
- * @param {GraphNode} graph_node
+ * @param {GraphNode | undefined} graph_node
  * @returns {string | undefined}
  */
 function getOutputNodeTitle(graph_node) {
+  if (!graph_node) {
+    return undefined;
+  }
+
   return (
-    getScalarGraphNodeField(graph_node.title) ??
-    getScalarGraphNodeField(graph_node.label) ??
+    getScalarGraphNodeField(getGraphNodeMetadataValue(graph_node, 'title')) ??
     getOutputNodePath(graph_node) ??
     getScalarGraphNodeField(graph_node.key)
   );
 }
 
 /**
- * @param {GraphNode} graph_node
+ * @param {GraphNode | undefined} graph_node
  * @returns {string | undefined}
  */
 function getOutputNodePath(graph_node) {
-  return getScalarGraphNodeField(graph_node.$path ?? graph_node.path);
+  if (!graph_node) {
+    return undefined;
+  }
+
+  return getScalarGraphNodeField(getGraphNodePath(graph_node));
 }
 
 /**
- * @param {GraphNode} graph_node
+ * @param {GraphNode | undefined} graph_node
  * @returns {string | undefined}
  */
 function getOutputNodeClass(graph_node) {
-  return getScalarGraphNodeField(graph_node.$class ?? graph_node.kind);
+  if (!graph_node) {
+    return undefined;
+  }
+
+  return getScalarGraphNodeField(getGraphNodeClassName(graph_node));
 }
 
 /**
@@ -275,20 +339,18 @@ function getOutputNodeClass(graph_node) {
  * @returns {string}
  */
 function getOutputNodeId(graph_node) {
-  return (
-    getScalarGraphNodeField(graph_node.$id ?? graph_node.id) ?? graph_node.id
-  );
+  return getGraphNodeId(graph_node);
 }
 
 /**
  * @param {{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }} resolved_link
- * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, document_node_ids?: BuildGraphResult['document_node_ids'], graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }} command_options
+ * @param {{ document_path_ids?: BuildGraphResult['document_path_ids'], graph_nodes?: BuildGraphResult['nodes'], repo_config?: PatramRepoConfig }} command_options
  * @returns {OutputResolvedLinkItem}
  */
 function createResolvedLinkOutputItem(resolved_link, command_options) {
   const target_graph_node = resolveDocumentGraphNode(
     command_options.graph_nodes,
-    command_options.document_node_ids,
+    command_options.document_path_ids,
     resolved_link.target.path,
   );
 
@@ -299,11 +361,6 @@ function createResolvedLinkOutputItem(resolved_link, command_options) {
     target: createResolvedLinkTarget(
       resolved_link.target,
       command_options.repo_config?.fields ?? {},
-      target_graph_node
-        ? (command_options.derived_summary_evaluator?.evaluate(
-            target_graph_node,
-          ) ?? null)
-        : null,
       target_graph_node,
     ),
   };
@@ -311,20 +368,20 @@ function createResolvedLinkOutputItem(resolved_link, command_options) {
 
 /**
  * @param {BuildGraphResult['nodes'] | undefined} graph_nodes
- * @param {BuildGraphResult['document_node_ids'] | undefined} document_node_ids
+ * @param {BuildGraphResult['document_path_ids'] | undefined} document_path_ids
  * @param {string} document_path
  * @returns {GraphNode | undefined}
  */
 function resolveDocumentGraphNode(
   graph_nodes,
-  document_node_ids,
+  document_path_ids,
   document_path,
 ) {
   if (!graph_nodes) {
     return undefined;
   }
 
-  return graph_nodes[resolveDocumentNodeId(document_node_ids, document_path)];
+  return graph_nodes[resolveDocumentNodeId(document_path_ids, document_path)];
 }
 
 /**
@@ -335,10 +392,10 @@ function resolveDocumentGraphNode(
 function collectOutputFields(graph_node, field_definitions) {
   /** @type {Record<string, string | string[]>} */
   const fields = {};
+  const metadata_entries = Object.entries(graph_node.metadata ?? {});
 
-  for (const [field_name, field_value] of Object.entries(graph_node)) {
+  for (const [field_name, field_value] of metadata_entries) {
     const normalized_value = getCollectedOutputFieldValue(
-      graph_node,
       field_name,
       field_value,
     );
@@ -355,7 +412,9 @@ function collectOutputFields(graph_node, field_definitions) {
       continue;
     }
 
-    const field_value = normalizeOutputFieldValue(graph_node[field_name]);
+    const field_value = normalizeOutputFieldValue(
+      getGraphNodeMetadataValue(graph_node, field_name),
+    );
 
     if (field_value !== undefined) {
       fields[field_name] = field_value;
@@ -366,12 +425,11 @@ function collectOutputFields(graph_node, field_definitions) {
 }
 
 /**
- * @param {GraphNode} graph_node
  * @param {string} field_name
  * @param {unknown} field_value
  * @returns {string | string[] | undefined}
  */
-function getCollectedOutputFieldValue(graph_node, field_name, field_value) {
+function getCollectedOutputFieldValue(field_name, field_value) {
   if (isInternalOutputField(field_name)) {
     return undefined;
   }
@@ -382,39 +440,9 @@ function getCollectedOutputFieldValue(graph_node, field_name, field_value) {
     return undefined;
   }
 
-  if (isLegacyMirrorOutputField(graph_node, field_name, normalized_value)) {
-    return undefined;
-  }
-
   return normalized_value;
 }
 
-/**
- * @param {GraphNode} graph_node
- * @param {string} field_name
- * @param {string | string[]} normalized_value
- * @returns {boolean}
- */
-function isLegacyMirrorOutputField(graph_node, field_name, normalized_value) {
-  if (Array.isArray(normalized_value)) {
-    return false;
-  }
-
-  if (field_name === 'kind') {
-    return normalized_value === graph_node.$class;
-  }
-
-  if (field_name === 'path') {
-    return normalized_value === graph_node.$path;
-  }
-
-  if (field_name === 'id') {
-    return normalized_value === graph_node.$id;
-  }
-
-  return false;
-}
-
 /**
  * @param {Record<string, string | string[]>} fields
  * @param {NonNullable<PatramRepoConfig['fields']>} field_definitions
@@ -423,7 +451,9 @@ function isLegacyMirrorOutputField(graph_node, field_name, normalized_value) {
 function createVisibleOutputFields(fields, field_definitions) {
   return Object.entries(fields)
     .filter(
-      ([field_name]) => field_definitions[field_name]?.display?.hidden !== true,
+      ([field_name]) =>
+        field_name !== 'description' &&
+        field_definitions[field_name]?.hidden !== true,
     )
     .sort(([left_name], [right_name]) =>
       compareOutputFieldNames(left_name, right_name, field_definitions),
@@ -436,16 +466,7 @@ function createVisibleOutputFields(fields, field_definitions) {
  * @returns {boolean}
  */
 function isInternalOutputField(field_name) {
-  return (
-    field_name === '$class' ||
-    field_name === '$id' ||
-    field_name === '$path' ||
-    field_name === 'id' ||
-    field_name === 'key' ||
-    field_name === 'label' ||
-    field_name === 'path' ||
-    field_name === 'title'
-  );
+  return field_name === 'title';
 }
 
 /**
@@ -456,9 +477,9 @@ function isInternalOutputField(field_name) {
  */
 function compareOutputFieldNames(left_name, right_name, field_definitions) {
   const left_order =
-    field_definitions[left_name]?.display?.order ?? Number.MAX_SAFE_INTEGER;
+    field_definitions[left_name]?.order ?? Number.MAX_SAFE_INTEGER;
   const right_order =
-    field_definitions[right_name]?.display?.order ?? Number.MAX_SAFE_INTEGER;
+    field_definitions[right_name]?.order ?? Number.MAX_SAFE_INTEGER;
 
   if (left_order !== right_order) {
     return left_order - right_order;

package/lib/parse/jsdoc/parse-jsdoc-blocks.js

@@ -10,7 +10,7 @@ export function collectJsdocBlocks(source_text) {
   const jsdoc_blocks = [];
 
   for (let line_index = 0; line_index < source_lines.length; line_index += 1) {
-    if (!source_lines[line_index].includes('/**')) {
+    if (!/^\s*\/\*\*/du.test(source_lines[line_index])) {
       continue;
     }
 

package/lib/parse/jsdoc/parse-jsdoc-claims.js

@@ -22,10 +22,10 @@ import { JSDOC_SOURCE_FILE_EXTENSIONS } from '../../config/source-file-defaults.
  * Activates one source anchor block, extracts directives and links, and
  * derives title and description claims from prose.
  *
- * Kind: parse
- * Status: active
- * Tracked in: ../../../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../../../docs/decisions/jsdoc-metadata-directive-syntax.md
+ * kind: parse
+ * status: active
+ * tracked_in: ../../../docs/plans/v0/source-anchor-dogfooding.md
+ * decided_by: ../../../docs/decisions/jsdoc-metadata-directive-syntax.md
  * @patram
  * @see {@link ../parse-claims.js}
  * @see {@link ../../../docs/decisions/jsdoc-metadata-directive-syntax.md}
@@ -34,7 +34,7 @@ import { JSDOC_SOURCE_FILE_EXTENSIONS } from '../../config/source-file-defaults.
 const JSDOC_EXTENSIONS = new Set(JSDOC_SOURCE_FILE_EXTENSIONS);
 const JSDOC_LINK_TAG_PATTERN = /^@(link|see)\s+(.+)$/du;
 const JSDOC_TAG_PATTERN = /^@[A-Za-z]+(?:\s|$)/du;
-const JSDOC_VISIBLE_DIRECTIVE_PATTERN = /^([A-Z][A-Za-z _-]*):\s+(.+)$/du;
+const JSDOC_VISIBLE_DIRECTIVE_PATTERN = /^([a-z][a-z0-9_]*):\s+(.+)$/du;
 
 /**
  * Parse JSDoc metadata claims from one source file.
@@ -160,8 +160,14 @@ function matchJsdocDirectiveFields(file_path, block_line) {
     return null;
   }
 
+  const directive_name = normalizeDirectiveName(directive_match[1]);
+
+  if (!directive_name) {
+    return null;
+  }
+
   return {
-    name: normalizeDirectiveName(directive_match[1]),
+    name: directive_name,
     origin: {
       column: block_line.column,
       line: block_line.line,