patram 0.6.2 → 0.8.0

package/lib/build-graph-identity.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Resolve the node key for one mapped claim.
+ *
+ * @param {{ field: string, key?: 'path' | 'value', class: string }} node_mapping
+ * @param {PatramClaim} claim
+ * @param {Map<string, string>} document_entity_keys
+ * @returns {string}
+ */
+export function resolveNodeKey(node_mapping: {
+    field: string;
+    key?: "path" | "value";
+    class: string;
+}, claim: PatramClaim, document_entity_keys: Map<string, string>): string;
+/**
+ * Resolve one edge target key and canonical path.
+ *
+ * @param {string} target_class
+ * @param {'path' | 'value'} target_type
+ * @param {PatramClaim} claim
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, DocumentNodeReference>} document_node_references
+ * @param {Set<string>} document_paths
+ * @returns {{ class_name: string, key: string, path?: string }}
+ */
+export function resolveTargetReference(target_class: string, target_type: "path" | "value", claim: PatramClaim, document_entity_keys: Map<string, string>, document_node_references: Map<string, DocumentNodeReference>, document_paths: Set<string>): {
+    class_name: string;
+    key: string;
+    path?: string;
+};
+/**
+ * Attach one canonical path to a graph node.
+ *
+ * @param {GraphNode} graph_node
+ * @param {string | undefined} source_path
+ */
+export function setCanonicalPath(graph_node: GraphNode, source_path: string | undefined): void;
+import type { PatramClaim } from './parse-claims.types.ts';
+import type { DocumentNodeReference } from './document-node-identity.js';
+import type { GraphNode } from './build-graph.types.ts';
+export { collectDocumentEntityKeys, collectDocumentNodeReferences, normalizeRepoRelativePath, resolveDocumentNodeId } from "./document-node-identity.js";

package/lib/build-graph.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Build a Patram graph from semantic config and parsed claims.
+ *
+ * @param {PatramConfig} patram_config
+ * @param {PatramClaim[]} claims
+ * @returns {BuildGraphResult}
+ */
+export function buildGraph(patram_config: PatramConfig, claims: PatramClaim[]): BuildGraphResult;
+import type { PatramConfig } from './patram-config.types.ts';
+import type { PatramClaim } from './parse-claims.types.ts';
+import type { BuildGraphResult } from './build-graph.types.ts';

package/lib/build-graph.types.d.ts

@@ -0,0 +1,24 @@
+import type { ClaimOrigin } from './parse-claims.types.ts';
+export interface GraphNode {
+    $class?: string;
+    $id?: string;
+    $path?: string;
+    id: string;
+    kind?: string;
+    key?: string;
+    path?: string;
+    title?: string;
+    [field: string]: string | string[] | undefined;
+}
+export interface GraphEdge {
+    from: string;
+    id: string;
+    origin: ClaimOrigin;
+    relation: string;
+    to: string;
+}
+export interface BuildGraphResult {
+    document_node_ids?: Record<string, string>;
+    edges: GraphEdge[];
+    nodes: Record<string, GraphNode>;
+}

package/lib/claim-helpers.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @param {string} target_value
+ * @returns {boolean}
+ */
+export function isPathLikeTarget(target_value: string): boolean;
+/**
+ * @param {string} file_path
+ * @param {number} claim_number
+ * @param {string} claim_type
+ * @param {PatramClaimFields} claim_fields
+ * @returns {PatramClaim}
+ */
+export function createClaim(file_path: string, claim_number: number, claim_type: string, claim_fields: PatramClaimFields): PatramClaim;
+/**
+ * @param {string} file_path
+ * @returns {string}
+ */
+export function getFileExtension(file_path: string): string;
+import type { PatramClaimFields } from './parse-claims.types.ts';
+import type { PatramClaim } from './parse-claims.types.ts';

package/lib/cli-help-metadata.js

@@ -50,6 +50,7 @@ export const COMMAND_NAMES = /** @type {const} */ ([
   'fields',
   'query',
   'queries',
+  'refs',
   'show',
 ]);
 
@@ -146,12 +147,12 @@ const COMMAND_DEFINITIONS = {
     ]),
     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 "$class=plan and none(in:tracked_in, $class=decision)"',
-      'patram query --where "count(in:decided_by, $class=task) = 0"',
+      "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 '$class=plan and none(in:tracked_in, $class=decision)'",
+      "patram query --where 'count(in:decided_by, $class=task) = 0'",
       'patram query ready-tasks --explain',
-      'patram query --where "$class=decision and status=accepted and count(in:decided_by, $class=task) = 0" --lint',
+      "patram query --where '$class=decision and status=accepted and count(in:decided_by, $class=task) = 0' --lint",
       'patram query active-plans --limit 10 --offset 20',
     ],
     extra_positionals_message:
@@ -161,12 +162,12 @@ const COMMAND_DEFINITIONS = {
     min_positionals: 0,
     missing_argument_examples: [
       'patram query active-plans',
-      'patram query --where "tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md"',
+      "patram query --where 'tracked_in=doc:docs/plans/v0/worktracking-agent-guidance.md'",
     ],
-    missing_argument_label: '<name> or --where "<clause>"',
+    missing_argument_label: "<name> or --where '<clause>'",
     missing_usage_lines: [
       'patram query <name> [options]',
-      'patram query --where "<clause>" [options]',
+      "patram query --where '<clause>' [options]",
     ],
     option_column_width: 19,
     options: [
@@ -214,7 +215,7 @@ const COMMAND_DEFINITIONS = {
     ],
     usage_lines: [
       'patram query <name> [options]',
-      'patram query --where "<clause>" [options]',
+      "patram query --where '<clause>' [options]",
     ],
   },
   queries: {
@@ -243,6 +244,44 @@ const COMMAND_DEFINITIONS = {
     summary: 'List the stored queries defined in the project configuration.',
     usage_lines: ['patram queries [options]'],
   },
+  refs: {
+    allowed_option_names: new Set(['where']),
+    examples: [
+      'patram refs docs/decisions/query-language.md',
+      "patram refs docs/decisions/query-language.md --where '$class=document'",
+      'patram refs docs/decisions/query-language.md --json',
+    ],
+    extra_positionals_message: 'Refs accepts exactly one file path.',
+    help_topics: ['query-language'],
+    max_positionals: 1,
+    min_positionals: 1,
+    missing_argument_examples: [
+      'patram refs docs/decisions/query-language.md',
+      "patram refs docs/patram.md --where '$class=document'",
+    ],
+    missing_argument_label: '<file>',
+    missing_usage_lines: ['patram refs <file>'],
+    option_column_width: 19,
+    options: [
+      {
+        description: 'Filter incoming source nodes with a where clause',
+        label: '--where <clause>',
+      },
+      {
+        description: 'Print plain text output',
+        label: '--plain',
+      },
+      {
+        description: 'Print JSON output',
+        label: '--json',
+      },
+    ],
+    related: ['show', 'query'],
+    root_summary: 'Inspect incoming graph references for one file',
+    summary:
+      'Inspect incoming graph references for one file, grouped by relation.',
+    usage_lines: ['patram refs <file> [options]'],
+  },
   show: {
     allowed_option_names: new Set(),
     examples: ['patram show docs/patram.md', 'patram show lib/patram-cli.js'],

package/lib/command-output.js

@@ -78,6 +78,7 @@ export function shouldPageCommandOutput(parsed_command, output_stream) {
     output_stream.isTTY === true &&
     (parsed_command.command_name === 'fields' ||
       parsed_command.command_name === 'query' ||
+      parsed_command.command_name === 'refs' ||
       parsed_command.command_name === 'show')
   );
 }

package/lib/document-node-identity.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @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: Record<string, MappingDefinition>, claims: PatramClaim[]): Map<string, string>;
+/**
+ * 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: Record<string, MappingDefinition>, claims: PatramClaim[]): Map<string, DocumentNodeReference>;
+/**
+ * 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: Record<string, string> | undefined, document_path: string): string;
+/**
+ * Normalize one repo-relative source path.
+ *
+ * @param {string} source_path
+ * @returns {string}
+ */
+export function normalizeRepoRelativePath(source_path: string): string;
+export type DocumentNodeReference = {
+    class_name: string;
+    id: string;
+    key: string;
+    path: string;
+};
+import type { MappingDefinition } from './patram-config.types.ts';
+import type { PatramClaim } from './parse-claims.types.ts';

package/lib/inspect-reverse-references.js

@@ -0,0 +1,184 @@
+/**
+ * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
+ * @import { PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ */
+
+import {
+  normalizeRepoRelativePath,
+  resolveDocumentNodeId,
+} from './document-node-identity.js';
+import { queryGraph } from './query-graph.js';
+
+/**
+ * Inspect incoming graph edges for one canonical target file.
+ *
+ * @param {BuildGraphResult} graph
+ * @param {string} target_file_path
+ * @param {PatramRepoConfig | undefined} repo_config
+ * @param {string | undefined} where_clause
+ * @returns {{
+ *   diagnostics: PatramDiagnostic[],
+ *   incoming: Record<string, GraphNode[]>,
+ *   node: GraphNode,
+ * }}
+ */
+export function inspectReverseReferences(
+  graph,
+  target_file_path,
+  repo_config,
+  where_clause,
+) {
+  const normalized_target_path = normalizeRepoRelativePath(target_file_path);
+  const target_node_id = resolveDocumentNodeId(
+    graph.document_node_ids,
+    normalized_target_path,
+  );
+  const target_node =
+    graph.nodes[target_node_id] ??
+    createFallbackTargetNode(target_node_id, normalized_target_path);
+  const allowed_source_node_ids = where_clause
+    ? resolveAllowedSourceNodeIds(graph, where_clause, repo_config)
+    : null;
+
+  if (allowed_source_node_ids && 'diagnostics' in allowed_source_node_ids) {
+    return {
+      diagnostics: allowed_source_node_ids.diagnostics,
+      incoming: {},
+      node: target_node,
+    };
+  }
+
+  return {
+    diagnostics: [],
+    incoming: collectIncomingGroups(
+      graph,
+      target_node.id,
+      allowed_source_node_ids,
+    ),
+    node: target_node,
+  };
+}
+
+/**
+ * @param {BuildGraphResult} graph
+ * @param {string} target_node_id
+ * @param {Set<string> | null} allowed_source_node_ids
+ * @returns {Record<string, GraphNode[]>}
+ */
+function collectIncomingGroups(graph, target_node_id, allowed_source_node_ids) {
+  /** @type {Map<string, Map<string, GraphNode>>} */
+  const grouped_incoming = new Map();
+
+  for (const graph_edge of graph.edges) {
+    if (graph_edge.to !== target_node_id) {
+      continue;
+    }
+
+    if (
+      allowed_source_node_ids &&
+      !allowed_source_node_ids.has(graph_edge.from)
+    ) {
+      continue;
+    }
+
+    const source_node = graph.nodes[graph_edge.from];
+
+    if (!source_node) {
+      continue;
+    }
+
+    let relation_sources = grouped_incoming.get(graph_edge.relation);
+
+    if (!relation_sources) {
+      relation_sources = new Map();
+      grouped_incoming.set(graph_edge.relation, relation_sources);
+    }
+
+    relation_sources.set(source_node.id, source_node);
+  }
+
+  return formatIncomingGroups(grouped_incoming);
+}
+
+/**
+ * @param {BuildGraphResult} graph
+ * @param {string} where_clause
+ * @param {PatramRepoConfig | undefined} repo_config
+ * @returns {{ diagnostics: PatramDiagnostic[] } | Set<string>}
+ */
+function resolveAllowedSourceNodeIds(graph, where_clause, repo_config) {
+  const query_result = queryGraph(
+    graph,
+    where_clause,
+    repo_config ?? {
+      fields: {},
+      include: [],
+      queries: {},
+    },
+  );
+
+  if (query_result.diagnostics.length > 0) {
+    return {
+      diagnostics: query_result.diagnostics,
+    };
+  }
+
+  return new Set(query_result.nodes.map((graph_node) => graph_node.id));
+}
+
+/**
+ * @param {Map<string, Map<string, GraphNode>>} grouped_incoming
+ * @returns {Record<string, GraphNode[]>}
+ */
+function formatIncomingGroups(grouped_incoming) {
+  /** @type {Record<string, GraphNode[]>} */
+  const incoming = {};
+
+  for (const relation_name of [...grouped_incoming.keys()].sort(
+    compareStrings,
+  )) {
+    const relation_sources = /** @type {Map<string, GraphNode>} */ (
+      grouped_incoming.get(relation_name)
+    );
+
+    incoming[relation_name] = [...relation_sources.values()].sort(
+      compareGraphNodes,
+    );
+  }
+
+  return incoming;
+}
+
+/**
+ * @param {string} node_id
+ * @param {string} target_path
+ * @returns {GraphNode}
+ */
+function createFallbackTargetNode(node_id, target_path) {
+  return {
+    $class: 'document',
+    $id: node_id,
+    $path: target_path,
+    id: node_id,
+    path: target_path,
+    title: target_path,
+  };
+}
+
+/**
+ * @param {GraphNode} left_node
+ * @param {GraphNode} right_node
+ * @returns {number}
+ */
+function compareGraphNodes(left_node, right_node) {
+  return compareStrings(left_node.id, right_node.id);
+}
+
+/**
+ * @param {string} left_value
+ * @param {string} right_value
+ * @returns {number}
+ */
+function compareStrings(left_value, right_value) {
+  return left_value.localeCompare(right_value, 'en');
+}

package/lib/layout-incoming-references.js

@@ -0,0 +1,105 @@
+/**
+ * @import { OutputNodeItem } from './output-view.types.ts';
+ */
+
+import { formatOutputNodeMetadataRows } from './format-output-metadata.js';
+import { formatNodeHeader } from './format-node-header.js';
+import { formatOutputItemBlock } from './format-output-item-block.js';
+
+/**
+ * Layout grouped incoming references as plain text lines.
+ *
+ * @param {Record<string, OutputNodeItem[]>} incoming
+ * @param {{
+ *   format_node_header?: (output_item: OutputNodeItem) => string,
+ *   format_relation_header?: (relation_name: string, relation_count: number) => string,
+ * }} layout_options
+ * @returns {string[]}
+ */
+export function layoutIncomingReferenceLines(incoming, layout_options = {}) {
+  const format_node_header =
+    layout_options.format_node_header ?? defaultNodeHeaderFormatter;
+  const format_relation_header =
+    layout_options.format_relation_header ?? defaultRelationHeaderFormatter;
+  /** @type {string[]} */
+  const output_lines = [];
+
+  for (const relation_name of Object.keys(incoming)) {
+    if (output_lines.length > 0) {
+      output_lines.push('');
+    }
+
+    const relation_sources = incoming[relation_name];
+
+    output_lines.push(
+      format_relation_header(relation_name, relation_sources.length),
+    );
+    output_lines.push(
+      ...layoutIncomingRelationSources(relation_sources, format_node_header),
+    );
+  }
+
+  return output_lines;
+}
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @returns {string}
+ */
+function defaultNodeHeaderFormatter(output_item) {
+  return formatNodeHeader(output_item);
+}
+
+/**
+ * @param {string} relation_name
+ * @param {number} relation_count
+ * @returns {string}
+ */
+function defaultRelationHeaderFormatter(relation_name, relation_count) {
+  return `${relation_name} (${relation_count})`;
+}
+
+/**
+ * @param {OutputNodeItem[]} relation_sources
+ * @param {(output_item: OutputNodeItem) => string} format_node_header
+ * @returns {string[]}
+ */
+function layoutIncomingRelationSources(relation_sources, format_node_header) {
+  /** @type {string[]} */
+  const output_lines = [];
+
+  for (const [item_index, output_item] of relation_sources.entries()) {
+    if (item_index > 0) {
+      output_lines.push('');
+    }
+
+    output_lines.push(
+      ...indentIncomingNodeBlock(
+        formatIncomingNodeBlock(output_item, format_node_header),
+      ),
+    );
+  }
+
+  return output_lines;
+}
+
+/**
+ * @param {OutputNodeItem} output_item
+ * @param {(output_item: OutputNodeItem) => string} format_node_header
+ * @returns {string}
+ */
+function formatIncomingNodeBlock(output_item, format_node_header) {
+  return formatOutputItemBlock({
+    header: format_node_header(output_item),
+    metadata_rows: formatOutputNodeMetadataRows(output_item),
+    title: output_item.title,
+  });
+}
+
+/**
+ * @param {string} block
+ * @returns {string[]}
+ */
+function indentIncomingNodeBlock(block) {
+  return block.split('\n').map((line) => (line.length > 0 ? `  ${line}` : ''));
+}

package/lib/layout-incoming-summary-lines.js

@@ -0,0 +1,21 @@
+/**
+ * Layout compact incoming-summary lines for `show`.
+ *
+ * @param {Record<string, number>} incoming_summary
+ * @returns {string[]}
+ */
+export function layoutIncomingSummaryLines(incoming_summary) {
+  const relation_names = Object.keys(incoming_summary);
+  const output_lines = ['incoming refs:'];
+
+  if (relation_names.length === 0) {
+    output_lines.push('  none');
+    return output_lines;
+  }
+
+  for (const relation_name of relation_names) {
+    output_lines.push(`  ${relation_name}: ${incoming_summary[relation_name]}`);
+  }
+
+  return output_lines;
+}

package/lib/list-source-files.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Source file scanning.
+ *
+ * Expands include globs into stable repo-relative file lists for indexing and
+ * broken-link validation.
+ *
+ * Kind: scan
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/source-scan.md
+ * @patram
+ * @see {@link ./load-project-graph.js}
+ * @see {@link ../docs/decisions/source-scan.md}
+ */
+/**
+ * List source files matched by Patram include globs.
+ *
+ * @param {string[]} include_patterns
+ * @param {string} [project_directory]
+ * @returns {Promise<string[]>}
+ */
+export function listSourceFiles(include_patterns: string[], project_directory?: string): Promise<string[]>;
+/**
+ * List repo files available for broken-link validation.
+ *
+ * @param {string} [project_directory]
+ * @returns {Promise<string[]>}
+ */
+export function listRepoFiles(project_directory?: string): Promise<string[]>;