patram 0.1.1 → 0.2.0

package/lib/build-graph-identity.js

@@ -77,6 +77,7 @@ export function resolveNodeKey(node_mapping, claim, document_entity_keys) {
  * @param {'path' | 'value'} target_type
  * @param {PatramClaim} claim
  * @param {Map<string, string>} document_entity_keys
+ * @param {Set<string>} document_paths
  * @returns {{ key: string, path?: string }}
  */
 export function resolveTargetReference(
@@ -84,12 +85,18 @@ export function resolveTargetReference(
   target_type,
   claim,
   document_entity_keys,
+  document_paths,
 ) {
   if (target_type === 'value') {
     return resolveValueTargetReference(target_kind, claim);
   }
 
-  return resolvePathTargetReference(target_kind, claim, document_entity_keys);
+  return resolvePathTargetReference(
+    target_kind,
+    claim,
+    document_entity_keys,
+    document_paths,
+  );
 }
 
 /**
@@ -176,15 +183,20 @@ function resolveValueTargetReference(target_kind, claim) {
  * @param {string} target_kind
  * @param {PatramClaim} claim
  * @param {Map<string, string>} document_entity_keys
+ * @param {Set<string>} document_paths
  * @returns {{ key: string, path?: string }}
  */
-function resolvePathTargetReference(target_kind, claim, document_entity_keys) {
-  const source_directory = posix.dirname(
-    normalizeRepoRelativePath(claim.origin.path),
-  );
+function resolvePathTargetReference(
+  target_kind,
+  claim,
+  document_entity_keys,
+  document_paths,
+) {
   const raw_target = getPathTargetValue(claim);
-  const target_path = normalizeRepoRelativePath(
-    posix.join(source_directory, raw_target),
+  const target_path = resolveDirectiveAwareTargetPath(
+    claim,
+    raw_target,
+    document_paths,
   );
 
   if (target_kind === 'document') {
@@ -204,6 +216,26 @@ function resolvePathTargetReference(target_kind, claim, document_entity_keys) {
   };
 }
 
+/**
+ * @param {PatramClaim} claim
+ * @param {string} raw_target
+ * @param {Set<string>} document_paths
+ * @returns {string}
+ */
+function resolveDirectiveAwareTargetPath(claim, raw_target, document_paths) {
+  const normalized_raw_target = normalizeRepoRelativePath(raw_target);
+
+  if (claim.type === 'directive' && document_paths.has(normalized_raw_target)) {
+    return normalized_raw_target;
+  }
+
+  const source_directory = posix.dirname(
+    normalizeRepoRelativePath(claim.origin.path),
+  );
+
+  return normalizeRepoRelativePath(posix.join(source_directory, raw_target));
+}
+
 /**
  * @param {PatramClaim} claim
  * @returns {string}

package/lib/build-graph.js

@@ -47,6 +47,10 @@ export function buildGraph(patram_config, claims) {
     patram_config.mappings,
     claims,
   );
+  /** @type {Set<string>} */
+  const document_paths = new Set(
+    claims.map((claim) => normalizeRepoRelativePath(claim.origin.path)),
+  );
 
   createDocumentNodes(graph_nodes, claims);
   applyNodeMappings(
@@ -60,6 +64,7 @@ export function buildGraph(patram_config, claims) {
     patram_config.mappings,
     claims,
     document_entity_keys,
+    document_paths,
   );
 
   return {
@@ -143,9 +148,16 @@ function applyNodeMappings(
  * @param {Record<string, MappingDefinition>} mappings
  * @param {PatramClaim[]} claims
  * @param {Map<string, string>} document_entity_keys
+ * @param {Set<string>} document_paths
  * @returns {GraphEdge[]}
  */
-function createGraphEdges(graph_nodes, mappings, claims, document_entity_keys) {
+function createGraphEdges(
+  graph_nodes,
+  mappings,
+  claims,
+  document_entity_keys,
+  document_paths,
+) {
   /** @type {GraphEdge[]} */
   const graph_edges = [];
   let edge_number = 0;
@@ -167,6 +179,7 @@ function createGraphEdges(graph_nodes, mappings, claims, document_entity_keys) {
       mapping_definition.emit.target,
       claim,
       document_entity_keys,
+      document_paths,
     );
     const target_node = upsertNode(
       graph_nodes,

package/lib/cli-help-metadata.js

@@ -0,0 +1,552 @@
+/* eslint-disable max-lines */
+/**
+ * @import {
+ *   CliCommandName,
+ *   CliHelpTopicName,
+ * } from './parse-cli-arguments.types.ts';
+ */
+
+/**
+ * @typedef {{
+ *   description: string,
+ *   label: string,
+ * }} CliHelpOption
+ */
+
+/**
+ * @typedef {{
+ *   allowed_option_names: Set<string>,
+ *   examples: string[],
+ *   extra_positionals_message: string,
+ *   help_topics: CliHelpTopicName[],
+ *   max_positionals: number,
+ *   min_positionals: number,
+ *   missing_argument_examples: string[],
+ *   missing_argument_label: string | null,
+ *   missing_usage_lines: string[],
+ *   option_column_width: number,
+ *   options: CliHelpOption[],
+ *   related: CliCommandName[],
+ *   root_summary: string,
+ *   summary: string,
+ *   syntax_lines?: string[],
+ *   usage_lines: string[],
+ * }} CliCommandDefinition
+ */
+
+/**
+ * @typedef {{
+ *   examples: string[],
+ *   lead: string,
+ *   operators: CliHelpOption[],
+ *   relation_terms: CliHelpOption[],
+ *   terms: string[],
+ *   usage_lines: string[],
+ * }} CliHelpTopicDefinition
+ */
+
+export const COMMAND_NAMES = /** @type {const} */ ([
+  'check',
+  'query',
+  'queries',
+  'show',
+]);
+
+export const HELP_TOPIC_NAMES = /** @type {const} */ (['query-language']);
+
+export const GLOBAL_OPTION_NAMES = new Set([
+  'help',
+  'plain',
+  'json',
+  'color',
+  'no-color',
+]);
+
+const ROOT_HELP_SUMMARY = 'Patram explores docs and how they link to sources.';
+const ROOT_HELP_USAGE_LINES = [
+  'patram <command> [options]',
+  'patram help [command]',
+];
+const ROOT_HELP_GLOBAL_OPTIONS = [
+  '--help',
+  '--plain',
+  '--json',
+  '--color <auto|always|never>',
+  '--no-color',
+];
+
+/** @type {Record<CliCommandName, CliCommandDefinition>} */
+const COMMAND_DEFINITIONS = {
+  check: {
+    allowed_option_names: new Set(),
+    examples: [
+      'patram check',
+      'patram check docs',
+      'patram check docs/patram.md',
+    ],
+    extra_positionals_message: 'Check accepts at most one path.',
+    help_topics: [],
+    max_positionals: 1,
+    min_positionals: 0,
+    missing_argument_examples: [],
+    missing_argument_label: null,
+    missing_usage_lines: ['patram check [path]'],
+    option_column_width: 10,
+    options: [
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['show', 'query'],
+    root_summary: 'Validate a project, directory, or file',
+    summary:
+      'Validate a project, directory, or file and report graph diagnostics.',
+    usage_lines: ['patram check [path] [options]'],
+  },
+  query: {
+    allowed_option_names: new Set([
+      'explain',
+      'limit',
+      'lint',
+      'offset',
+      'where',
+    ]),
+    examples: [
+      'patram query active-plans',
+      'patram query --where "tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md"',
+      'patram query --where "status not in [done, dropped, superseded]"',
+      'patram query --where "kind=plan and none(in:tracked_in, kind=decision)"',
+      'patram query --where "count(in:decided_by, kind=task) = 0"',
+      'patram query ready-tasks --explain',
+      'patram query --where "kind=decision and status=accepted and count(in:decided_by, kind=task) = 0" --lint',
+      'patram query active-plans --limit 10 --offset 20',
+    ],
+    extra_positionals_message:
+      'Query accepts either "--where" or a stored query name.',
+    help_topics: ['query-language'],
+    max_positionals: 1,
+    min_positionals: 0,
+    missing_argument_examples: [
+      'patram query active-plans',
+      'patram query --where "tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md"',
+    ],
+    missing_argument_label: '<name> or --where "<clause>"',
+    missing_usage_lines: [
+      'patram query <name> [options]',
+      'patram query --where "<clause>" [options]',
+    ],
+    option_column_width: 19,
+    options: [
+      {
+        description: 'Run an ad hoc query instead of a stored query',
+        label: '--where <clause>',
+      },
+      {
+        description: 'Skip the first N matches',
+        label: '--offset <number>',
+      },
+      {
+        description: 'Limit the number of matches',
+        label: '--limit <number>',
+      },
+      {
+        description: 'Explain the resolved query without rendering results',
+        label: '--explain',
+      },
+      {
+        description: 'Validate syntax and relation references only',
+        label: '--lint',
+      },
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['queries', 'show'],
+    root_summary: 'Run a stored query or an ad hoc where clause',
+    summary:
+      'Run a stored query or an ad hoc where clause against graph nodes.',
+    syntax_lines: [
+      'id=<value> | kind=<value> | path=<value> | status=<value>',
+      'id^=<prefix> | path^=<prefix> | title~<text>',
+      '<field> in [<value>, ...] | <field> not in [<value>, ...]',
+      '<relation>:* | <relation>=<target-id>',
+      'any(<traversal>, <term> and <term>)',
+      'none(<traversal>, <term> and <term>)',
+      'count(<traversal>, <term> and <term>) <comparison> <number>',
+    ],
+    usage_lines: [
+      'patram query <name> [options]',
+      'patram query --where "<clause>" [options]',
+    ],
+  },
+  queries: {
+    allowed_option_names: new Set(),
+    examples: ['patram queries'],
+    extra_positionals_message: 'Queries does not accept positional arguments.',
+    help_topics: [],
+    max_positionals: 0,
+    min_positionals: 0,
+    missing_argument_examples: [],
+    missing_argument_label: null,
+    missing_usage_lines: ['patram queries'],
+    option_column_width: 10,
+    options: [
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['query'],
+    root_summary: 'List stored queries',
+    summary: 'List the stored queries defined in the project configuration.',
+    usage_lines: ['patram queries [options]'],
+  },
+  show: {
+    allowed_option_names: new Set(),
+    examples: ['patram show docs/patram.md', 'patram show lib/patram-cli.js'],
+    extra_positionals_message: 'Show accepts exactly one file path.',
+    help_topics: [],
+    max_positionals: 1,
+    min_positionals: 1,
+    missing_argument_examples: [
+      'patram show docs/patram.md',
+      'patram show lib/patram-cli.js',
+    ],
+    missing_argument_label: '<file>',
+    missing_usage_lines: ['patram show <file>'],
+    option_column_width: 10,
+    options: [
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['query', 'check'],
+    root_summary: 'Print a file with resolved links',
+    summary:
+      'Print one source file with indexed links resolved against the graph.',
+    usage_lines: ['patram show <file> [options]'],
+  },
+};
+
+/** @type {Record<CliHelpTopicName, CliHelpTopicDefinition>} */
+const HELP_TOPIC_DEFINITIONS = {
+  'query-language': {
+    examples: [
+      'kind=decision and status=accepted',
+      'path^=docs/plans/',
+      'title~query',
+      'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md',
+      'implements_command=command:query',
+      'status not in [done, dropped, superseded]',
+      'any(in:tracked_in, kind=task and status in [pending, ready, in_progress, blocked])',
+      'none(in:tracked_in, kind=decision)',
+      'count(in:decided_by, kind=task) = 0',
+      'not uses_term=term:graph',
+    ],
+    lead: 'Query language filters graph nodes with field, relation, traversal, and aggregate terms.',
+    operators: [
+      {
+        description: 'Exact field match or exact count comparison',
+        label: '=',
+      },
+      {
+        description: 'Prefix match for id and path',
+        label: '^=',
+      },
+      {
+        description: 'Contains text for title',
+        label: '~',
+      },
+      {
+        description: 'Set membership for supported fields',
+        label: 'in',
+      },
+      {
+        description: 'Set exclusion for supported fields',
+        label: 'not in',
+      },
+      {
+        description: 'Negate one term',
+        label: 'not',
+      },
+      {
+        description: 'Combine terms',
+        label: 'and',
+      },
+      {
+        description: 'Count comparisons',
+        label: '!= < > >= <=',
+      },
+    ],
+    relation_terms: [
+      {
+        description: 'Match nodes with at least one outgoing relation',
+        label: '<relation>:*',
+      },
+      {
+        description: 'Match nodes linked to an exact target id',
+        label: '<relation>=<target-id>',
+      },
+      {
+        description: 'Traverse one incoming relation hop',
+        label: 'in:<relation>',
+      },
+      {
+        description: 'Traverse one outgoing relation hop',
+        label: 'out:<relation>',
+      },
+    ],
+    terms: [
+      'Exact match: id, kind, path, status',
+      'Prefix match: id, path',
+      'Contains text: title',
+      'Set membership: id, kind, path, status, title',
+    ],
+    usage_lines: [
+      '<field>=<value>',
+      'id^=<prefix>',
+      'path^=<prefix>',
+      'title~<text>',
+      '<field> in [<value>, ...]',
+      '<field> not in [<value>, ...]',
+      '<relation>:*',
+      '<relation>=<target-id>',
+      'any(<traversal>, <term> and <term>)',
+      'none(<traversal>, <term> and <term>)',
+      'count(<traversal>, <term> and <term>) <comparison> <number>',
+      'not <term>',
+      '<term> and <term>',
+    ],
+  },
+};
+
+/**
+ * @returns {{ global_options: string[], summary: string, usage_lines: string[] }}
+ */
+export function getRootHelpDefinition() {
+  return {
+    global_options: ROOT_HELP_GLOBAL_OPTIONS,
+    summary: ROOT_HELP_SUMMARY,
+    usage_lines: ROOT_HELP_USAGE_LINES,
+  };
+}
+
+/**
+ * @param {CliCommandName} command_name
+ * @returns {CliCommandDefinition}
+ */
+export function getCommandDefinition(command_name) {
+  return COMMAND_DEFINITIONS[command_name];
+}
+
+/**
+ * @param {CliHelpTopicName} help_topic_name
+ * @returns {CliHelpTopicDefinition}
+ */
+export function getHelpTopicDefinition(help_topic_name) {
+  return HELP_TOPIC_DEFINITIONS[help_topic_name];
+}
+
+/**
+ * @param {string | undefined} command_name
+ * @returns {command_name is CliCommandName}
+ */
+export function isCommandName(command_name) {
+  return COMMAND_NAMES.includes(
+    /** @type {CliCommandName} */ (command_name ?? ''),
+  );
+}
+
+/**
+ * @param {string | undefined} help_topic_name
+ * @returns {help_topic_name is CliHelpTopicName}
+ */
+export function isHelpTopicName(help_topic_name) {
+  return HELP_TOPIC_NAMES.includes(
+    /** @type {CliHelpTopicName} */ (help_topic_name ?? ''),
+  );
+}
+
+/**
+ * @param {string} input_text
+ * @returns {CliCommandName | undefined}
+ */
+export function findCommandSuggestion(input_text) {
+  return /** @type {CliCommandName | undefined} */ (
+    findCloseMatch(input_text, COMMAND_NAMES)
+  );
+}
+
+/**
+ * @param {string} input_text
+ * @returns {CliCommandName | CliHelpTopicName | undefined}
+ */
+export function findHelpTargetSuggestion(input_text) {
+  return /** @type {CliCommandName | CliHelpTopicName | undefined} */ (
+    findCloseMatch(input_text, [...COMMAND_NAMES, ...HELP_TOPIC_NAMES])
+  );
+}
+
+/**
+ * @param {string} input_text
+ * @param {CliCommandName | undefined} command_name
+ * @returns {string | undefined}
+ */
+export function findOptionSuggestion(input_text, command_name) {
+  const candidates = listOptionLabels(command_name);
+
+  return findCloseMatch(input_text, candidates);
+}
+
+/**
+ * @returns {CliCommandName[]}
+ */
+export function listCommandNames() {
+  return [...COMMAND_NAMES];
+}
+
+/**
+ * @returns {CliHelpTopicName[]}
+ */
+export function listHelpTopicNames() {
+  return [...HELP_TOPIC_NAMES];
+}
+
+/**
+ * @param {CliCommandName | undefined} command_name
+ * @returns {string[]}
+ */
+function listOptionLabels(command_name) {
+  const option_labels = new Set(
+    [...GLOBAL_OPTION_NAMES].map((option_name) => `--${option_name}`),
+  );
+
+  if (command_name) {
+    for (const option_name of getCommandDefinition(command_name)
+      .allowed_option_names) {
+      option_labels.add(`--${option_name}`);
+    }
+  } else {
+    option_labels.add('--limit');
+    option_labels.add('--offset');
+    option_labels.add('--where');
+  }
+
+  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(right_text.length + 1).fill(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];
+}