patram 0.9.0 → 0.10.0

package/lib/cli/arguments.types.d.ts

@@ -0,0 +1,63 @@
+export type CliCommandName = 'check' | 'fields' | 'query' | 'queries' | 'refs' | 'show';
+export type CliHelpTopicName = 'query-language';
+export type CliHelpTargetKind = 'root' | 'command' | 'topic';
+export type CliUnexpectedArgumentCommandName = CliCommandName | 'help';
+export type CliOutputMode = 'default' | 'plain' | 'json';
+export type CliColorMode = 'auto' | 'always' | 'never';
+export interface ParsedCliCommandRequest {
+    kind?: 'command';
+    color_mode: CliColorMode;
+    command_arguments: string[];
+    command_name: CliCommandName;
+    output_mode: CliOutputMode;
+    query_inspection_mode?: 'explain' | 'lint';
+    query_limit?: number;
+    query_offset?: number;
+}
+export interface ParsedCliHelpRequest {
+    kind: 'help';
+    target_kind: CliHelpTargetKind;
+    target_name?: CliCommandName | CliHelpTopicName;
+}
+export type ParsedCliArguments = ParsedCliCommandRequest;
+export type ParsedCliRequest = ParsedCliCommandRequest | ParsedCliHelpRequest;
+export type CliParseError = {
+    code: 'message';
+    message: string;
+} | {
+    code: 'missing_required_argument';
+    argument_label: string;
+    command_name: 'query' | 'refs' | 'show';
+} | {
+    code: 'unexpected_argument';
+    command_name: CliUnexpectedArgumentCommandName;
+    token: string;
+} | {
+    code: 'option_not_valid_for_command';
+    command_name: CliCommandName;
+    token: string;
+} | {
+    code: 'unknown_command';
+    suggestion?: CliCommandName;
+    token: string;
+} | {
+    code: 'unknown_help_target';
+    suggestion?: CliCommandName | CliHelpTopicName;
+    token: string;
+} | {
+    code: 'unknown_stored_query';
+    name: string;
+    suggestion?: string;
+} | {
+    code: 'unknown_option';
+    command_name?: CliCommandName;
+    suggestion?: string;
+    token: string;
+};
+export type ParseCliArgumentsResult = {
+    success: true;
+    value: ParsedCliRequest;
+} | {
+    error: CliParseError;
+    success: false;
+};

package/lib/cli/commands/query.js

@@ -12,7 +12,10 @@ import {
 } from '../../output/command-output.js';
 import { createDerivedSummaryEvaluator } from '../../output/derived-summary.js';
 import { renderCheckDiagnostics } from '../../output/render-check-output.js';
-import { renderInvalidWhereDiagnostic } from '../render-help.js';
+import {
+  renderCliParseError,
+  renderInvalidWhereDiagnostic,
+} from '../render-help.js';
 import { createOutputView } from '../../output/render-output-view.js';
 import { loadPatramConfig } from '../../config/load-patram-config.js';
 import { loadProjectGraph } from '../../graph/load-project-graph.js';
@@ -60,7 +63,7 @@ export async function runQueryCommand(parsed_command, io_context) {
   );
 
   if (!where_clause.success) {
-    io_context.stderr.write(`${where_clause.message}\n`);
+    io_context.stderr.write(renderCliParseError(where_clause.error));
 
     return 1;
   }
@@ -139,7 +142,7 @@ async function runQueryInspectionCommand(
   );
 
   if (!where_clause.success) {
-    io_context.stderr.write(`${where_clause.message}\n`);
+    io_context.stderr.write(renderCliParseError(where_clause.error));
 
     return 1;
   }

package/lib/cli/help-metadata.js

@@ -6,6 +6,8 @@
  * } from './arguments.types.ts';
  */
 
+import { findCloseMatch } from '../find-close-match.js';
+
 /**
  * @typedef {{
  *   description: string,
@@ -532,100 +534,3 @@ function listOptionLabels(command_name) {
 
   return [...option_labels];
 }
-
-/**
- * @param {string} input_text
- * @param {readonly string[]} candidates
- * @returns {string | undefined}
- */
-function findCloseMatch(input_text, candidates) {
-  let best_candidate;
-  let best_score = 0;
-
-  for (const candidate of candidates) {
-    const score = scoreCandidate(input_text, candidate);
-
-    if (score > best_score) {
-      best_candidate = candidate;
-      best_score = score;
-    }
-  }
-
-  if (best_score < 0.6) {
-    return undefined;
-  }
-
-  return best_candidate;
-}
-
-/**
- * @param {string} input_text
- * @param {string} candidate
- * @returns {number}
- */
-function scoreCandidate(input_text, candidate) {
-  const max_length = Math.max(input_text.length, candidate.length);
-
-  if (max_length === 0) {
-    return 1;
-  }
-
-  return (
-    1 - calculateDamerauLevenshteinDistance(input_text, candidate) / max_length
-  );
-}
-
-/**
- * @param {string} left_text
- * @param {string} right_text
- * @returns {number}
- */
-function calculateDamerauLevenshteinDistance(left_text, right_text) {
-  /** @type {number[][]} */
-  const matrix = Array.from({ length: left_text.length + 1 }, () =>
-    Array.from({ length: right_text.length + 1 }, () => 0),
-  );
-
-  for (let left_index = 0; left_index <= left_text.length; left_index += 1) {
-    matrix[left_index][0] = left_index;
-  }
-
-  for (
-    let right_index = 0;
-    right_index <= right_text.length;
-    right_index += 1
-  ) {
-    matrix[0][right_index] = right_index;
-  }
-
-  for (let left_index = 1; left_index <= left_text.length; left_index += 1) {
-    for (
-      let right_index = 1;
-      right_index <= right_text.length;
-      right_index += 1
-    ) {
-      const substitution_cost =
-        left_text[left_index - 1] === right_text[right_index - 1] ? 0 : 1;
-
-      matrix[left_index][right_index] = Math.min(
-        matrix[left_index - 1][right_index] + 1,
-        matrix[left_index][right_index - 1] + 1,
-        matrix[left_index - 1][right_index - 1] + substitution_cost,
-      );
-
-      if (
-        left_index > 1 &&
-        right_index > 1 &&
-        left_text[left_index - 1] === right_text[right_index - 2] &&
-        left_text[left_index - 2] === right_text[right_index - 1]
-      ) {
-        matrix[left_index][right_index] = Math.min(
-          matrix[left_index][right_index],
-          matrix[left_index - 2][right_index - 2] + 1,
-        );
-      }
-    }
-  }
-
-  return matrix[left_text.length][right_text.length];
-}

package/lib/cli/parse-arguments-helpers.js

@@ -67,9 +67,7 @@ export function validateHelpCommandLine(command_line) {
   }
 
   if (command_line.positionals.length > 2) {
-    return createMessageParseError(
-      'Help accepts at most one topic or command.',
-    );
+    return createUnexpectedArgumentError('help', command_line.positionals[2]);
   }
 
   return null;
@@ -422,8 +420,9 @@ function validateCommandPositionals(command_name, command_positionals) {
   }
 
   if (command_positionals.length > command_definition.max_positionals) {
-    return createMessageParseError(
-      command_definition.extra_positionals_message,
+    return createUnexpectedArgumentError(
+      command_name,
+      command_positionals[command_definition.max_positionals],
     );
   }
 
@@ -451,3 +450,16 @@ function isKnownCommandOptionName(option_name) {
     option_name === 'where'
   );
 }
+
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @param {string | undefined} token
+ * @returns {CliParseError}
+ */
+function createUnexpectedArgumentError(command_name, token) {
+  return {
+    code: 'unexpected_argument',
+    command_name,
+    token: token ?? '',
+  };
+}

package/lib/cli/render-help.js

@@ -75,6 +75,20 @@ export function renderCliParseError(parse_error) {
     );
   }
 
+  if (parse_error.code === 'unexpected_argument') {
+    return renderUnexpectedArgumentError(
+      parse_error.command_name,
+      parse_error.token,
+    );
+  }
+
+  if (parse_error.code === 'unknown_stored_query') {
+    return renderUnknownStoredQueryError(
+      parse_error.name,
+      parse_error.suggestion,
+    );
+  }
+
   return `${parse_error.message}\n`;
 }
 
@@ -326,6 +340,49 @@ function renderMissingRequiredArgumentError(command_name, argument_label) {
   ]);
 }
 
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @param {string} invalid_token
+ * @returns {string}
+ */
+function renderUnexpectedArgumentError(command_name, invalid_token) {
+  return joinOutputLines([
+    `Unexpected argument: ${invalid_token}`,
+    '',
+    'Usage:',
+    ...indentLines(getUnexpectedArgumentUsageLines(command_name)),
+    '',
+    'Next:',
+    `  ${renderUnexpectedArgumentNext(command_name)}`,
+  ]);
+}
+
+/**
+ * @param {string} stored_query_name
+ * @param {string | undefined} suggestion
+ * @returns {string}
+ */
+function renderUnknownStoredQueryError(stored_query_name, suggestion) {
+  if (suggestion) {
+    return joinOutputLines([
+      `Unknown stored query: ${stored_query_name}`,
+      '',
+      'Did you mean:',
+      `  ${suggestion}`,
+      '',
+      'Next:',
+      `  patram query ${suggestion}`,
+    ]);
+  }
+
+  return joinOutputLines([
+    `Unknown stored query: ${stored_query_name}`,
+    '',
+    'Next:',
+    '  patram queries',
+  ]);
+}
+
 /**
  * @param {string} invalid_token
  * @param {CliCommandName | CliHelpTopicName | undefined} suggestion
@@ -378,6 +435,30 @@ function renderCommandHelpPath(command_name) {
   return `patram help ${command_name}`;
 }
 
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @returns {string}
+ */
+function renderUnexpectedArgumentNext(command_name) {
+  if (command_name === 'help') {
+    return 'patram --help';
+  }
+
+  return renderCommandHelpPath(command_name);
+}
+
+/**
+ * @param {'help' | CliCommandName} command_name
+ * @returns {string[]}
+ */
+function getUnexpectedArgumentUsageLines(command_name) {
+  if (command_name === 'help') {
+    return ['patram help [command]'];
+  }
+
+  return getCommandDefinition(command_name).usage_lines;
+}
+
 /**
  * @param {string[]} lines
  * @returns {string[]}

package/lib/config/schema.d.ts

@@ -141,6 +141,7 @@ export const patram_repo_config_schema: z.ZodObject<{
         prefixes: z.ZodArray<z.ZodString>;
     }, z.core.$strict>>>;
     queries: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
         where: z.ZodString;
     }, z.core.$strict>>>;
     relations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
@@ -167,6 +168,7 @@ import { z } from 'zod';
  * @typedef {z.output<typeof stored_query_schema>} StoredQueryConfig
  */
 declare const stored_query_schema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
     where: z.ZodString;
 }, z.core.$strict>;
 /**

package/lib/config/schema.js

@@ -27,6 +27,10 @@ const MIXED_STYLE_VALUES = new Set(['ignore', 'error']);
  */
 const stored_query_schema = z
   .object({
+    description: z
+      .string()
+      .min(1, 'Stored query "description" must not be empty.')
+      .optional(),
     where: z.string().min(1, 'Stored query "where" must not be empty.'),
   })
   .strict();

package/lib/find-close-match.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Find the closest candidate above the shared suggestion threshold.
+ *
+ * @param {string} input_text
+ * @param {readonly string[]} candidates
+ * @returns {string | undefined}
+ */
+export function findCloseMatch(input_text: string, candidates: readonly string[]): string | undefined;

package/lib/find-close-match.js

@@ -0,0 +1,98 @@
+/**
+ * Find the closest candidate above the shared suggestion threshold.
+ *
+ * @param {string} input_text
+ * @param {readonly string[]} candidates
+ * @returns {string | undefined}
+ */
+export function findCloseMatch(input_text, candidates) {
+  let best_candidate;
+  let best_score = 0;
+
+  for (const candidate of candidates) {
+    const score = scoreCandidate(input_text, candidate);
+
+    if (score > best_score) {
+      best_candidate = candidate;
+      best_score = score;
+    }
+  }
+
+  if (best_score < 0.6) {
+    return undefined;
+  }
+
+  return best_candidate;
+}
+
+/**
+ * @param {string} input_text
+ * @param {string} candidate
+ * @returns {number}
+ */
+function scoreCandidate(input_text, candidate) {
+  const max_length = Math.max(input_text.length, candidate.length);
+
+  if (max_length === 0) {
+    return 1;
+  }
+
+  return (
+    1 - calculateDamerauLevenshteinDistance(input_text, candidate) / max_length
+  );
+}
+
+/**
+ * @param {string} left_text
+ * @param {string} right_text
+ * @returns {number}
+ */
+function calculateDamerauLevenshteinDistance(left_text, right_text) {
+  /** @type {number[][]} */
+  const matrix = Array.from({ length: left_text.length + 1 }, () =>
+    Array.from({ length: right_text.length + 1 }, () => 0),
+  );
+
+  for (let left_index = 0; left_index <= left_text.length; left_index += 1) {
+    matrix[left_index][0] = left_index;
+  }
+
+  for (
+    let right_index = 0;
+    right_index <= right_text.length;
+    right_index += 1
+  ) {
+    matrix[0][right_index] = right_index;
+  }
+
+  for (let left_index = 1; left_index <= left_text.length; left_index += 1) {
+    for (
+      let right_index = 1;
+      right_index <= right_text.length;
+      right_index += 1
+    ) {
+      const substitution_cost =
+        left_text[left_index - 1] === right_text[right_index - 1] ? 0 : 1;
+
+      matrix[left_index][right_index] = Math.min(
+        matrix[left_index - 1][right_index] + 1,
+        matrix[left_index][right_index - 1] + 1,
+        matrix[left_index - 1][right_index - 1] + substitution_cost,
+      );
+
+      if (
+        left_index > 1 &&
+        right_index > 1 &&
+        left_text[left_index - 1] === right_text[right_index - 2] &&
+        left_text[left_index - 2] === right_text[right_index - 1]
+      ) {
+        matrix[left_index][right_index] = Math.min(
+          matrix[left_index][right_index],
+          matrix[left_index - 2][right_index - 2] + substitution_cost,
+        );
+      }
+    }
+  }
+
+  return matrix[left_text.length][right_text.length];
+}

package/lib/graph/query/resolve.d.ts

@@ -1,6 +1,3 @@
-/**
- * @import { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
- */
 /**
  * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
  */
@@ -9,7 +6,7 @@
  *
  * @param {PatramRepoConfig} repo_config
  * @param {string[]} command_arguments
- * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { success: false, message: string }}
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { error: CliParseError, success: false }}
  */
 export function resolveWhereClause(repo_config: PatramRepoConfig, command_arguments: string[]): {
     success: true;
@@ -18,8 +15,8 @@ export function resolveWhereClause(repo_config: PatramRepoConfig, command_argume
         where_clause: string;
     };
 } | {
+    error: CliParseError;
     success: false;
-    message: string;
 };
 export type QuerySource = {
     kind: "ad_hoc";
@@ -28,3 +25,4 @@ export type QuerySource = {
     name: string;
 };
 import type { PatramRepoConfig } from '../../config/load-patram-config.types.d.ts';
+import type { CliParseError } from '../../cli/arguments.types.d.ts';

package/lib/graph/query/resolve.js

@@ -1,7 +1,10 @@
 /**
+ * @import { CliParseError } from '../../cli/arguments.types.ts';
  * @import { PatramRepoConfig } from '../../config/load-patram-config.types.ts';
  */
 
+import { findCloseMatch } from '../../find-close-match.js';
+
 /**
  * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
  */
@@ -11,7 +14,7 @@
  *
  * @param {PatramRepoConfig} repo_config
  * @param {string[]} command_arguments
- * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { success: false, message: string }}
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { error: CliParseError, success: false }}
  */
 export function resolveWhereClause(repo_config, command_arguments) {
   if (command_arguments[0] === '--where') {
@@ -19,7 +22,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
     if (where_clause.length === 0) {
       return {
-        message: 'Query requires a where clause.',
+        error: {
+          code: 'message',
+          message: 'Query requires a where clause.',
+        },
         success: false,
       };
     }
@@ -39,7 +45,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
   if (!stored_query_name) {
     return {
-      message: 'Query requires "--where" or a stored query name.',
+      error: {
+        code: 'message',
+        message: 'Query requires "--where" or a stored query name.',
+      },
       success: false,
     };
   }
@@ -48,7 +57,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
   if (!stored_query) {
     return {
-      message: `Stored query "${stored_query_name}" was not found.`,
+      error: createUnknownStoredQueryError(
+        stored_query_name,
+        Object.keys(repo_config.queries),
+      ),
       success: false,
     };
   }
@@ -64,3 +76,25 @@ export function resolveWhereClause(repo_config, command_arguments) {
     },
   };
 }
+
+/**
+ * @param {string} stored_query_name
+ * @param {string[]} stored_query_names
+ * @returns {CliParseError}
+ */
+function createUnknownStoredQueryError(stored_query_name, stored_query_names) {
+  const suggestion = findCloseMatch(stored_query_name, stored_query_names);
+
+  if (!suggestion) {
+    return {
+      code: 'unknown_stored_query',
+      name: stored_query_name,
+    };
+  }
+
+  return {
+    code: 'unknown_stored_query',
+    name: stored_query_name,
+    suggestion,
+  };
+}

package/lib/output/layout-stored-queries.js

@@ -10,7 +10,7 @@ const MIN_TERM_COLUMN_WIDTH = 20;
 const STORED_QUERY_COLUMN_GAP = 2;
 
 /**
- * @typedef {'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain'} StoredQuerySegmentKind
+ * @typedef {'description' | 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain'} StoredQuerySegmentKind
  */
 
 /**
@@ -56,7 +56,8 @@ function layoutStoredQuery(output_item, name_column_width, term_column_width) {
     name_column_width + STORED_QUERY_COLUMN_GAP,
   );
 
-  return term_lines.map((line_segments, line_index) => {
+  /** @type {StoredQuerySegment[][]} */
+  const output_lines = term_lines.map((line_segments, line_index) => {
     if (line_index === 0) {
       return [
         {
@@ -79,6 +80,21 @@ function layoutStoredQuery(output_item, name_column_width, term_column_width) {
       ...line_segments,
     ];
   });
+
+  if (output_item.description) {
+    for (const description_line of output_item.description.split('\n')) {
+      output_lines.push([
+        {
+          kind: 'description',
+          text: `${' '.repeat(name_column_width + STORED_QUERY_COLUMN_GAP)}${description_line}`,
+        },
+      ]);
+    }
+  }
+
+  output_lines.push([]);
+
+  return output_lines;
 }
 
 /**

package/lib/output/list-queries.js

@@ -6,12 +6,13 @@
  * List stored queries in stable name order.
  *
  * @param {Record<string, StoredQueryConfig>} stored_queries
- * @returns {{ name: string, where: string }[]}
+ * @returns {{ name: string, where: string, description?: string }[]}
  */
 export function listQueries(stored_queries) {
   return Object.entries(stored_queries)
     .sort(([left_name], [right_name]) => left_name.localeCompare(right_name))
     .map(([name, stored_query]) => ({
+      description: stored_query.description,
       name,
       where: stored_query.where,
     }));

package/lib/output/renderers/json.js

@@ -92,9 +92,6 @@ function renderJsonRefsOutput(output_view) {
 function renderJsonShowOutput(output_view) {
   return `${JSON.stringify(
     {
-      document: output_view.document
-        ? formatJsonNodeItem(output_view.document)
-        : undefined,
       incoming_summary: output_view.incoming_summary,
       source: output_view.source,
       resolved_links: output_view.items.map(formatJsonResolvedLink),
@@ -144,13 +141,20 @@ function formatJsonNodeItem(output_item) {
 
 /**
  * @param {OutputStoredQueryItem} output_item
- * @returns {{ name: string, where: string }}
+ * @returns {{ name: string, where: string, description?: string }}
  */
 function formatJsonStoredQuery(output_item) {
-  return {
+  /** @type {{ description?: string, name: string, where: string }} */
+  const stored_query = {
     name: output_item.name,
     where: output_item.where,
   };
+
+  if (output_item.description) {
+    stored_query.description = output_item.description;
+  }
+
+  return stored_query;
 }
 
 /**

package/lib/output/renderers/plain.js

@@ -24,7 +24,7 @@ export function renderPlainOutput(output_view) {
   }
 
   if (output_view.command === 'queries') {
-    return renderPlainStoredQueries(output_view.items);
+    return renderPlainStoredQueries(output_view);
   }
 
   if (output_view.command === 'refs') {
@@ -69,17 +69,23 @@ function renderPlainEmptyQuery(footer) {
 }
 
 /**
- * @param {OutputStoredQueryItem[]} output_items
+ * @param {Extract<OutputView, { command: 'queries' }>} output_view
  * @returns {string}
  */
-function renderPlainStoredQueries(output_items) {
-  if (output_items.length === 0) {
+function renderPlainStoredQueries(output_view) {
+  if (output_view.items.length === 0) {
     return '';
   }
 
-  return `${layoutStoredQueries(output_items)
-    .map(formatPlainStoredQueryLine)
-    .join('\n')}\n`;
+  const output_lines = layoutStoredQueries(output_view.items).map(
+    formatPlainStoredQueryLine,
+  );
+
+  if (output_view.hints.length === 0) {
+    return `${output_lines.join('\n')}\n`;
+  }
+
+  return `${output_lines.join('\n')}\n${output_view.hints.join('\n')}\n`;
 }
 
 /**
@@ -88,29 +94,12 @@ function renderPlainStoredQueries(output_items) {
  */
 function renderPlainShowOutput(output_view) {
   const rendered_source = trimTrailingLineBreaks(output_view.rendered_source);
-  const document_summary = output_view.document
-    ? formatPlainNodeItem(output_view.document)
-    : '';
   const incoming_summary = renderPlainIncomingSummary(output_view);
 
-  if (
-    document_summary.length === 0 &&
-    output_view.items.length === 0 &&
-    incoming_summary.length === 0
-  ) {
+  if (output_view.items.length === 0 && incoming_summary.length === 0) {
     return `${rendered_source}\n`;
   }
-
-  /** @type {string[]} */
-  const summary_items = [];
-
-  if (document_summary.length > 0) {
-    summary_items.push(document_summary);
-  }
-
-  summary_items.push(...output_view.items.map(formatPlainResolvedLinkItem));
-
-  const summary_blocks = summary_items.filter((summary_item) => summary_item);
+  const summary_blocks = output_view.items.map(formatPlainResolvedLinkItem);
 
   if (incoming_summary.length > 0) {
     summary_blocks.push(incoming_summary);

package/lib/output/renderers/rich.js

@@ -33,7 +33,7 @@ export async function renderRichOutput(output_view, render_options) {
   }
 
   if (output_view.command === 'queries') {
-    return renderRichStoredQueries(output_view.items, ansi);
+    return renderRichStoredQueries(output_view, ansi);
   }
 
   if (output_view.command === 'refs') {
@@ -83,18 +83,24 @@ function renderRichEmptyQuery(footer, ansi) {
 }
 
 /**
- * @param {OutputStoredQueryItem[]} output_items
+ * @param {Extract<OutputView, { command: 'queries' }>} output_view
  * @param {Ansis} ansi
  * @returns {string}
  */
-function renderRichStoredQueries(output_items, ansi) {
-  if (output_items.length === 0) {
+function renderRichStoredQueries(output_view, ansi) {
+  if (output_view.items.length === 0) {
     return '';
   }
 
-  return `${layoutStoredQueries(output_items)
-    .map((line_segments) => formatRichStoredQueryLine(line_segments, ansi))
-    .join('\n')}\n`;
+  const output_lines = layoutStoredQueries(output_view.items).map(
+    (line_segments) => formatRichStoredQueryLine(line_segments, ansi),
+  );
+
+  if (output_view.hints.length === 0) {
+    return `${output_lines.join('\n')}\n`;
+  }
+
+  return `${output_lines.join('\n')}\n${output_view.hints.map((hint) => ansi.gray(hint)).join('\n')}\n`;
 }
 
 /**
@@ -107,28 +113,14 @@ async function renderRichShowOutput(output_view, render_options, ansi) {
   const rendered_source = trimTrailingLineBreaks(
     await renderRichSource(output_view, render_options),
   );
-  const document_summary = output_view.document
-    ? formatRichNodeItem(output_view.document, ansi)
-    : '';
   const incoming_summary = renderRichIncomingSummary(output_view, ansi);
 
-  if (
-    document_summary.length === 0 &&
-    output_view.items.length === 0 &&
-    incoming_summary.length === 0
-  ) {
+  if (output_view.items.length === 0 && incoming_summary.length === 0) {
     return `${rendered_source}\n`;
   }
 
-  /** @type {string[]} */
-  const summary_items = [];
-
-  if (document_summary.length > 0) {
-    summary_items.push(document_summary);
-  }
-
-  summary_items.push(
-    ...output_view.items.map((item) => formatRichResolvedLinkItem(item, ansi)),
+  const summary_items = output_view.items.map((item) =>
+    formatRichResolvedLinkItem(item, ansi),
   );
 
   if (incoming_summary.length > 0) {
@@ -173,7 +165,7 @@ function formatRichNodeItem(output_item, ansi) {
 }
 
 /**
- * @param {{ kind: 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }[]} line_segments
+ * @param {{ kind: 'description' | 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }[]} line_segments
  * @param {Ansis} ansi
  * @returns {string}
  */
@@ -232,7 +224,7 @@ function createAnsi(color_enabled) {
 }
 
 /**
- * @param {{ kind: 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }} line_segment
+ * @param {{ kind: 'description' | 'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain', text: string }} line_segment
  * @param {Ansis} ansi
  * @returns {string}
  */
@@ -241,6 +233,10 @@ function styleStoredQuerySegment(line_segment, ansi) {
     return ansi.green(line_segment.text);
   }
 
+  if (line_segment.kind === 'description') {
+    return ansi.gray(line_segment.text);
+  }
+
   if (line_segment.kind === 'operator') {
     return ansi.gray(line_segment.text);
   }

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

@@ -12,7 +12,7 @@ import { resolveDocumentNodeId } from '../../graph/build-graph-identity.js';
  * Create a shared output view from one command result.
  *
  * @param {'query' | 'queries'} command_name
- * @param {GraphNode[] | { name: string, where: string }[]} command_items
+ * @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
  * @returns {OutputView}
  */
@@ -41,23 +41,8 @@ export function createOutputView(command_name, command_items, command_options) {
  * @returns {ShowOutputView}
  */
 export function createShowOutputView(show_output, command_options = {}) {
-  const shown_document_node = resolveDocumentGraphNode(
-    command_options.graph_nodes,
-    command_options.document_node_ids,
-    show_output.path,
-  );
-
   return {
     command: 'show',
-    document: shown_document_node
-      ? createOutputNodeItem(
-          shown_document_node,
-          command_options.derived_summary_evaluator?.evaluate(
-            shown_document_node,
-          ) ?? null,
-          command_options.repo_config?.fields ?? {},
-        )
-      : undefined,
     hints: [],
     incoming_summary: show_output.incoming_summary,
     items: show_output.resolved_links.map((resolved_link) =>
@@ -144,17 +129,19 @@ function createQueryOutputView(graph_nodes, command_options = {}) {
 }
 
 /**
- * @param {{ name: string, where: string }[]} stored_queries
+ * @param {{ name: string, where: string, description?: string }[]} stored_queries
  * @returns {OutputView}
  */
 function createStoredQueriesOutputView(stored_queries) {
   return {
     command: 'queries',
-    hints: [],
+    hints:
+      stored_queries.length === 0 ? [] : ['Hint: patram help query-language'],
     items: stored_queries.map((stored_query) => ({
       kind: 'stored_query',
       name: stored_query.name,
       where: stored_query.where,
+      description: stored_query.description,
     })),
     summary: {
       count: stored_queries.length,

package/lib/scan/discover-fields.js

@@ -20,6 +20,11 @@ import { resolve } from 'node:path';
 import { DEFAULT_INCLUDE_PATTERNS } from '../config/source-file-defaults.js';
 import { listSourceFiles } from './list-source-files.js';
 import { parseSourceFile } from '../parse/parse-claims.js';
+import {
+  matchHiddenDirectiveFields,
+  matchVisibleDirectiveFields,
+} from '../parse/markdown/parse-markdown-directives.js';
+import { isPathLikeTarget } from '../parse/claim-helpers.js';
 
 /**
  * Field discovery from source claims.
@@ -71,10 +76,9 @@ export async function discoverFields(
   options,
 ) {
   const defined_field_names = options?.defined_field_names ?? new Set();
-  const source_file_paths = await listSourceFiles(
-    DEFAULT_INCLUDE_PATTERNS,
-    project_directory,
-  );
+  const source_file_paths = (
+    await listSourceFiles(DEFAULT_INCLUDE_PATTERNS, project_directory)
+  ).filter((source_file_path) => source_file_path.includes('/'));
   const parse_results = await Promise.all(
     source_file_paths.map(async (source_file_path) => {
       const source_text = await readFile(
@@ -88,6 +92,7 @@ export async function discoverFields(
           source: source_text,
         }).claims,
         path: source_file_path,
+        source_text,
       };
     }),
   );
@@ -107,13 +112,20 @@ export async function discoverFields(
       }
     }
 
+    const allowed_markdown_lines = collectAllowedMarkdownDirectiveLines(
+      parse_result.path,
+      parse_result.source_text,
+      parse_result.claims,
+    );
+
     return parse_result.claims.flatMap((claim) => {
       if (
         claim.type !== 'directive' ||
         !claim.name ||
         claim.name.startsWith('$') ||
         typeof claim.value !== 'string' ||
-        claim.value.length === 0
+        claim.value.length === 0 ||
+        !shouldIncludeDiscoveryClaim(claim, allowed_markdown_lines)
       ) {
         return [];
       }
@@ -123,6 +135,7 @@ export async function discoverFields(
           class_names: new Set(document_classes),
           document_id: claim.document_id,
           name: claim.name,
+          normalized_value: normalizeDiscoveryValue(claim.value),
           origin: claim.origin,
           value: claim.value,
         },
@@ -147,7 +160,9 @@ export async function discoverFields(
   const fields = [...field_buckets.values()]
     .map(buildFieldSuggestion)
     .filter(
-      (field_suggestion) => !defined_field_names.has(field_suggestion.name),
+      (field_suggestion) =>
+        !defined_field_names.has(field_suggestion.name) &&
+        isPlausibleFieldName(field_suggestion.name),
     )
     .sort((left_suggestion, right_suggestion) =>
       left_suggestion.confidence !== right_suggestion.confidence
@@ -182,7 +197,10 @@ function buildFieldSuggestion(field_bucket) {
   const conflicting_evidence = buildEvidenceReferences(
     field_bucket.observations.filter(
       (field_observation) =>
-        scoreFieldValue(field_observation.value, type_result.name) === 0,
+        scoreFieldValue(
+          field_observation.normalized_value,
+          type_result.name,
+        ) === 0,
     ),
   );
 
@@ -228,12 +246,13 @@ function buildEvidenceReferences(observations) {
 function inferFieldMultiplicity(observations) {
   /** @type {Map<string, Set<string>>} */
   const values_by_document = observations.reduce((values, observation) => {
+    const normalized_value = observation.normalized_value;
     const current_values = values.get(observation.document_id);
 
     if (current_values) {
-      current_values.add(observation.value);
+      current_values.add(normalized_value);
     } else {
-      values.set(observation.document_id, new Set([observation.value]));
+      values.set(observation.document_id, new Set([normalized_value]));
     }
 
     return values;
@@ -369,7 +388,7 @@ function scoreFieldType(observations, field_type_name) {
 
   const total_score = observations.reduce(
     (sum, observation) =>
-      sum + scoreFieldValue(observation.value, field_type_name),
+      sum + scoreFieldValue(observation.normalized_value, field_type_name),
     0,
   );
 
@@ -423,6 +442,7 @@ const FIELD_TYPE_SCORERS = {
  *   class_names: Set<string>,
  *   document_id: string,
  *   name: string,
+ *   normalized_value: string,
  *   origin: ClaimOrigin,
  *   value: string,
  * }} FieldObservation
@@ -434,3 +454,109 @@ const FIELD_TYPE_SCORERS = {
  *   observations: FieldObservation[],
  * }} FieldBucket
  */
+
+/**
+ * @param {PatramClaim} claim
+ * @param {Set<number> | null} allowed_markdown_lines
+ * @returns {boolean}
+ */
+function shouldIncludeDiscoveryClaim(claim, allowed_markdown_lines) {
+  if (claim.parser !== 'markdown') {
+    return true;
+  }
+
+  if (claim.markdown_style === 'front_matter') {
+    return true;
+  }
+
+  return allowed_markdown_lines?.has(claim.origin.line) ?? false;
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} source_text
+ * @param {PatramClaim[]} claims
+ * @returns {Set<number> | null}
+ */
+function collectAllowedMarkdownDirectiveLines(file_path, source_text, claims) {
+  if (!file_path.endsWith('.md')) {
+    return null;
+  }
+
+  const title_claim = claims.find((claim) => claim.type === 'document.title');
+
+  if (!title_claim) {
+    return new Set();
+  }
+
+  const lines = source_text.split('\n');
+  /** @type {Set<number>} */
+  const allowed_lines = new Set();
+
+  for (
+    let line_index = title_claim.origin.line;
+    line_index < lines.length;
+    line_index += 1
+  ) {
+    const line = lines[line_index];
+
+    if (line.trim().length === 0) {
+      continue;
+    }
+
+    if (isMarkdownDiscoveryDirective(file_path, line, line_index + 1)) {
+      allowed_lines.add(line_index + 1);
+      continue;
+    }
+
+    break;
+  }
+
+  return allowed_lines;
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {boolean}
+ */
+function isMarkdownDiscoveryDirective(file_path, line, line_number) {
+  return (
+    matchVisibleDirectiveFields(file_path, line, line_number) !== null ||
+    matchHiddenDirectiveFields(file_path, line, line_number) !== null
+  );
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeDiscoveryValue(value) {
+  const trimmed_value = value.trim();
+  const markdown_link_match = trimmed_value.match(
+    /^\[([^\]]+)\]\(([^)]+)\)$/du,
+  );
+
+  if (markdown_link_match && isPathLikeTarget(markdown_link_match[2])) {
+    return markdown_link_match[2];
+  }
+
+  const code_span_match = trimmed_value.match(/^`([^`]+)`[.,;:]?$/du);
+
+  if (code_span_match) {
+    return code_span_match[1];
+  }
+
+  return trimmed_value;
+}
+
+/**
+ * @param {string} field_name
+ * @returns {boolean}
+ */
+function isPlausibleFieldName(field_name) {
+  const field_name_tokens = field_name.split('_');
+
+  return field_name.length <= 32 && field_name_tokens.length <= 4;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patram",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "main": "./lib/patram.js",
   "types": "./lib/patram.d.ts",