patram 0.6.2 → 0.8.0

package/lib/render-plain-output.js

@@ -1,5 +1,5 @@
 /**
- * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, ShowOutputView } from './output-view.types.ts';
+ * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, RefsOutputView, ShowOutputView } from './output-view.types.ts';
  */
 
 import {
@@ -8,6 +8,8 @@ import {
 } from './format-output-metadata.js';
 import { formatNodeHeader } from './format-node-header.js';
 import { formatOutputItemBlock } from './format-output-item-block.js';
+import { layoutIncomingReferenceLines } from './layout-incoming-references.js';
+import { layoutIncomingSummaryLines } from './layout-incoming-summary-lines.js';
 import { layoutStoredQueries } from './layout-stored-queries.js';
 
 /**
@@ -25,6 +27,10 @@ export function renderPlainOutput(output_view) {
     return renderPlainStoredQueries(output_view.items);
   }
 
+  if (output_view.command === 'refs') {
+    return renderPlainRefsOutput(output_view);
+  }
+
   if (output_view.command === 'show') {
     return renderPlainShowOutput(output_view);
   }
@@ -85,8 +91,13 @@ function renderPlainShowOutput(output_view) {
   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) {
+  if (
+    document_summary.length === 0 &&
+    output_view.items.length === 0 &&
+    incoming_summary.length === 0
+  ) {
     return `${rendered_source}\n`;
   }
 
@@ -99,7 +110,28 @@ function renderPlainShowOutput(output_view) {
 
   summary_items.push(...output_view.items.map(formatPlainResolvedLinkItem));
 
-  return `${rendered_source}\n\n----------------\n${summary_items.join('\n\n')}\n`;
+  const summary_blocks = summary_items.filter((summary_item) => summary_item);
+
+  if (incoming_summary.length > 0) {
+    summary_blocks.push(incoming_summary);
+  }
+
+  return `${rendered_source}\n\n----------------\n${summary_blocks.join('\n\n')}\n`;
+}
+
+/**
+ * @param {RefsOutputView} output_view
+ * @returns {string}
+ */
+function renderPlainRefsOutput(output_view) {
+  const node_summary = formatPlainNodeItem(output_view.node);
+  const output_lines = layoutIncomingReferenceLines(output_view.incoming);
+
+  if (output_lines.length === 0) {
+    return `${node_summary}\n\nNo incoming references.\n`;
+  }
+
+  return `${node_summary}\n\n${output_lines.join('\n')}\n`;
 }
 
 /**
@@ -135,6 +167,17 @@ function formatPlainResolvedLinkItem(output_item) {
   });
 }
 
+/**
+ * @param {ShowOutputView} output_view
+ * @returns {string}
+ */
+function renderPlainIncomingSummary(output_view) {
+  const output_lines = layoutIncomingSummaryLines(output_view.incoming_summary);
+  output_lines.push('', `Hint: patram refs ${output_view.path}`);
+
+  return output_lines.join('\n');
+}
+
 /**
  * @param {string} value
  * @returns {string}

package/lib/render-rich-output.js

@@ -1,6 +1,6 @@
 /**
  * @import { CliColorMode } from './parse-cli-arguments.types.ts';
- * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, ShowOutputView } from './output-view.types.ts';
+ * @import { OutputNodeItem, OutputResolvedLinkItem, OutputStoredQueryItem, OutputView, QueryOutputView, RefsOutputView, ShowOutputView } from './output-view.types.ts';
  */
 
 import { Ansis } from 'ansis';
@@ -11,6 +11,8 @@ import {
 } from './format-output-metadata.js';
 import { formatNodeHeader } from './format-node-header.js';
 import { formatOutputItemBlock } from './format-output-item-block.js';
+import { layoutIncomingReferenceLines } from './layout-incoming-references.js';
+import { layoutIncomingSummaryLines } from './layout-incoming-summary-lines.js';
 import { layoutStoredQueries } from './layout-stored-queries.js';
 import { renderRichSource } from './render-rich-source.js';
 
@@ -34,6 +36,9 @@ export async function renderRichOutput(output_view, render_options) {
     return renderRichStoredQueries(output_view.items, ansi);
   }
 
+  if (output_view.command === 'refs') {
+    return renderRichRefsOutput(output_view, ansi);
+  }
   if (output_view.command === 'show') {
     return renderRichShowOutput(output_view, render_options, ansi);
   }
@@ -105,10 +110,7 @@ async function renderRichShowOutput(output_view, render_options, ansi) {
   const document_summary = output_view.document
     ? formatRichNodeItem(output_view.document, ansi)
     : '';
-
-  if (document_summary.length === 0 && output_view.items.length === 0) {
-    return `${rendered_source}\n`;
-  }
+  const incoming_summary = renderRichIncomingSummary(output_view, ansi);
 
   /** @type {string[]} */
   const summary_items = [];
@@ -121,9 +123,34 @@ async function renderRichShowOutput(output_view, render_options, ansi) {
     ...output_view.items.map((item) => formatRichResolvedLinkItem(item, ansi)),
   );
 
+  if (incoming_summary.length > 0) {
+    summary_items.push(incoming_summary);
+  }
+
   return `${rendered_source}\n\n${ansi.gray(FULL_WIDTH_DIVIDER)}\n\n${summary_items.join('\n\n')}\n`;
 }
 
+/**
+ * @param {RefsOutputView} output_view
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichRefsOutput(output_view, ansi) {
+  const node_summary = formatRichNodeItem(output_view.node, ansi);
+  const output_lines = layoutIncomingReferenceLines(output_view.incoming, {
+    format_node_header(output_item) {
+      return ansi.green(formatNodeHeader(output_item));
+    },
+    format_relation_header(relation_name, relation_count) {
+      return `${ansi.bold(relation_name)} ${ansi.gray(`(${relation_count})`)}`;
+    },
+  });
+
+  return output_lines.length === 0
+    ? `${node_summary}\n\n${ansi.yellow('No incoming references.')}\n`
+    : `${node_summary}\n\n${output_lines.join('\n')}\n`;
+}
+
 /**
  * @param {OutputNodeItem} output_item
  * @param {Ansis} ansi
@@ -162,6 +189,24 @@ function formatRichResolvedLinkItem(output_item, ansi) {
   });
 }
 
+/**
+ * @param {ShowOutputView} output_view
+ * @param {Ansis} ansi
+ * @returns {string}
+ */
+function renderRichIncomingSummary(output_view, ansi) {
+  const output_lines = layoutIncomingSummaryLines(output_view.incoming_summary);
+  output_lines[0] = ansi.bold(output_lines[0]);
+
+  if (Object.keys(output_view.incoming_summary).length === 0) {
+    output_lines[1] = `  ${ansi.gray('none')}`;
+  }
+
+  output_lines.push('', ansi.gray(`Hint: patram refs ${output_view.path}`));
+
+  return output_lines.join('\n');
+}
+
 /**
  * @param {boolean} color_enabled
  * @returns {Ansis}

package/lib/resolve-patram-graph-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Merge built-in Patram graph semantics with repo-defined schema.
+ *
+ * @param {PatramRepoConfig} repo_config
+ * @returns {PatramConfig}
+ */
+export function resolvePatramGraphConfig(repo_config: PatramRepoConfig): PatramConfig;
+import type { PatramRepoConfig } from './load-patram-config.types.ts';
+import type { PatramConfig } from './patram-config.types.ts';

package/lib/reverse-reference-test-helpers.js

@@ -0,0 +1,76 @@
+/**
+ * Shared reverse-reference graph fixtures for tests.
+ */
+
+export function createDecisionNode() {
+  return {
+    $class: 'decision',
+    $id: 'decision:query-language',
+    $path: 'docs/decisions/query-language.md',
+    id: 'decision:query-language',
+    path: 'docs/decisions/query-language.md',
+    status: 'accepted',
+    title: 'Query Language',
+  };
+}
+
+export function createReconcileNode() {
+  return {
+    $class: 'document',
+    $id: 'doc:lib/reconcile.js',
+    $path: 'lib/reconcile.js',
+    id: 'doc:lib/reconcile.js',
+    path: 'lib/reconcile.js',
+    title: 'Reconciler entrypoint.',
+  };
+}
+
+export function createResumeNode() {
+  return {
+    $class: 'document',
+    $id: 'doc:lib/resume.js',
+    $path: 'lib/resume.js',
+    id: 'doc:lib/resume.js',
+    path: 'lib/resume.js',
+    title: 'Resume entrypoint.',
+  };
+}
+
+export function createTaskNode() {
+  return {
+    $class: 'task',
+    $id: 'task:reverse-reference-inspection',
+    $path: 'docs/tasks/v0/reverse-reference-inspection.md',
+    id: 'task:reverse-reference-inspection',
+    path: 'docs/tasks/v0/reverse-reference-inspection.md',
+    status: 'ready',
+    title: 'Implement reverse reference inspection',
+  };
+}
+
+/**
+ * @param {string} edge_id
+ * @param {string} from_id
+ * @param {string} origin_path
+ * @param {string} relation_name
+ * @param {string} to_id
+ */
+export function createGraphEdge(
+  edge_id,
+  from_id,
+  origin_path,
+  relation_name,
+  to_id,
+) {
+  return {
+    from: from_id,
+    id: edge_id,
+    origin: {
+      column: 1,
+      line: 1,
+      path: origin_path,
+    },
+    relation: relation_name,
+    to: to_id,
+  };
+}

package/lib/show-document.js

@@ -1,6 +1,6 @@
 /* eslint-disable max-lines */
 /**
- * @import { GraphNode } from './build-graph.types.ts';
+ * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
  * @import { PatramClaim } from './parse-claims.types.ts';
  * @import { PatramDiagnostic } from './load-patram-config.types.ts';
  */
@@ -9,6 +9,7 @@ import { readFile } from 'node:fs/promises';
 import { posix, relative, resolve } from 'node:path';
 
 import { resolveDocumentNodeId } from './build-graph-identity.js';
+import { inspectReverseReferences } from './inspect-reverse-references.js';
 import { parseSourceFile } from './parse-claims.js';
 
 /**
@@ -30,11 +31,12 @@ import { parseSourceFile } from './parse-claims.js';
 /**
  * @param {string} requested_file_path
  * @param {string} project_directory
- * @param {import('./build-graph.types.ts').BuildGraphResult} graph
+ * @param {BuildGraphResult} graph
  * @returns {Promise<
  *   | {
  *       success: true;
  *       value: {
+ *         incoming_summary: Record<string, number>;
  *         path: string;
  *         rendered_source: string;
  *         resolved_links: Array<{
@@ -93,6 +95,7 @@ export async function loadShowOutput(
       source_file_path,
       source_text,
       parse_result.claims,
+      graph,
       graph.document_node_ids,
       graph.nodes,
     ),
@@ -103,14 +106,16 @@ export async function loadShowOutput(
  * @param {string} source_file_path
  * @param {string} source_text
  * @param {PatramClaim[]} claims
+ * @param {BuildGraphResult} graph
  * @param {import('./build-graph.types.ts').BuildGraphResult['document_node_ids']} document_node_ids
  * @param {Record<string, GraphNode>} graph_nodes
- * @returns {{ path: string, rendered_source: string, resolved_links: Array<{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }>, source: string }}
+ * @returns {{ 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 }}
  */
 function createShowOutput(
   source_file_path,
   source_text,
   claims,
+  graph,
   document_node_ids,
   graph_nodes,
 ) {
@@ -125,8 +130,15 @@ function createShowOutput(
       graph_nodes,
     ),
   );
+  const reverse_references = inspectReverseReferences(
+    graph,
+    source_file_path,
+    undefined,
+    undefined,
+  );
 
   return {
+    incoming_summary: summarizeIncomingReferences(reverse_references.incoming),
     path: source_file_path,
     rendered_source: renderResolvedSource(
       source_text,
@@ -269,12 +281,23 @@ function getScalarGraphField(field_value) {
  * @returns {{ kind?: string, path: string, status?: string, title: string }}
  */
 function createResolvedLinkTarget(target_node, target_path, fallback_title) {
-  return {
-    kind: getResolvedLinkTargetKind(target_node),
+  /** @type {{ kind?: string, path: string, status?: string, title: string }} */
+  const resolved_target = {
     path: getResolvedLinkTargetPath(target_node, target_path),
-    status: getScalarGraphField(target_node?.status),
     title: getScalarGraphField(target_node?.title) ?? fallback_title,
   };
+  const target_kind = getResolvedLinkTargetKind(target_node);
+  const target_status = getScalarGraphField(target_node?.status);
+
+  if (target_kind) {
+    resolved_target.kind = target_kind;
+  }
+
+  if (target_status) {
+    resolved_target.status = target_status;
+  }
+
+  return resolved_target;
 }
 
 /**
@@ -355,6 +378,21 @@ function trimTrailingLineBreaks(value) {
   return value.replace(/\n+$/du, '');
 }
 
+/**
+ * @param {Record<string, GraphNode[]>} incoming
+ * @returns {Record<string, number>}
+ */
+function summarizeIncomingReferences(incoming) {
+  /** @type {Record<string, number>} */
+  const incoming_summary = {};
+
+  for (const relation_name of Object.keys(incoming)) {
+    incoming_summary[relation_name] = incoming[relation_name].length;
+  }
+
+  return incoming_summary;
+}
+
 /**
  * @param {unknown} error
  * @returns {error is NodeJS.ErrnoException}

package/lib/source-file-defaults.d.ts

@@ -0,0 +1,5 @@
+export const MARKDOWN_SOURCE_FILE_EXTENSIONS: string[];
+export const YAML_SOURCE_FILE_EXTENSIONS: string[];
+export const JSDOC_SOURCE_FILE_EXTENSIONS: string[];
+export const SUPPORTED_SOURCE_FILE_EXTENSIONS: string[];
+export const DEFAULT_INCLUDE_PATTERNS: string[];

package/lib/tagged-fenced-block-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @import { TaggedFencedBlockError } from './tagged-fenced-blocks.types.ts';
+ */
+/**
+ * @param {string} code
+ * @param {string} message
+ * @returns {TaggedFencedBlockError}
+ */
+export function createTaggedFencedBlockError(code: string, message: string): TaggedFencedBlockError;
+import type { TaggedFencedBlockError } from './tagged-fenced-blocks.types.ts';

package/lib/tagged-fenced-block-markdown.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @param {string[]} lines
+ * @returns {number}
+ */
+export function findMarkdownBodyStartLineIndex(lines: string[]): number;
+/**
+ * @param {string[]} lines
+ * @param {number} body_start
+ * @returns {string}
+ */
+export function getMarkdownTitle(lines: string[], body_start: number): string;
+/**
+ * @param {string} line
+ * @returns {{ level: number, text: string } | null}
+ */
+export function parseHeading(line: string): {
+    level: number;
+    text: string;
+} | null;
+/**
+ * @param {string[]} heading_path
+ * @param {string} title
+ * @param {{ level: number, text: string }} heading
+ * @returns {string[]}
+ */
+export function updateHeadingPath(heading_path: string[], title: string, heading: {
+    level: number;
+    text: string;
+}): string[];
+/**
+ * @param {string} line
+ * @returns {{ character: string, lang: string, length: number } | null}
+ */
+export function parseOpeningMarkdownFence(line: string): {
+    character: string;
+    lang: string;
+    length: number;
+} | null;
+/**
+ * @param {string} line
+ * @param {{ character: string, length: number }} open_fence
+ * @returns {boolean}
+ */
+export function isClosingMarkdownFence(line: string, open_fence: {
+    character: string;
+    length: number;
+}): boolean;

package/lib/tagged-fenced-block-metadata.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @param {string} file_path
+ * @param {{ metadata: Record<string, string>, tag_lines: number[] }} pending_tag_set
+ * @param {{ metadata: Record<string, string>, tag_lines: number[] }} next_tag_set
+ * @returns {{ metadata: Record<string, string>, tag_lines: number[] }}
+ */
+export function mergePendingTagSets(file_path: string, pending_tag_set: {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+}, next_tag_set: {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+}): {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+};
+/**
+ * @param {string} file_path
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {{ metadata: Record<string, string>, tag_lines: number[] } | null}
+ */
+export function parseTaggedMetadataLine(file_path: string, line: string, line_number: number): {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+} | null;

package/lib/tagged-fenced-block-parser.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @typedef {{ metadata: Record<string, string>, tag_lines: number[] }} PendingTagSet
+ */
+/**
+ * @typedef {{
+ *   heading_path: string[];
+ *   lang: string;
+ *   line_start: number;
+ *   metadata: Record<string, string>;
+ *   tag_lines: number[];
+ *   value_lines: string[];
+ * }} OpenTaggedBlock
+ */
+/**
+ * @typedef {{ character: string, lang: string, length: number }} OpenFence
+ */
+/**
+ * @typedef {{
+ *   blocks: TaggedFencedBlock[];
+ *   body_start: number;
+ *   heading_path: string[];
+ *   open_fence: OpenFence | null;
+ *   open_tagged_block: OpenTaggedBlock | null;
+ *   pending_tag_set: PendingTagSet | null;
+ *   title: string;
+ * }} TaggedBlockScannerState
+ */
+/**
+ * @param {TaggedFencedBlocksInput} input
+ * @returns {TaggedFencedBlockFile}
+ */
+export function extractTaggedFencedBlocksFromSource(input: TaggedFencedBlocksInput): TaggedFencedBlockFile;
+export type PendingTagSet = {
+    metadata: Record<string, string>;
+    tag_lines: number[];
+};
+export type OpenTaggedBlock = {
+    heading_path: string[];
+    lang: string;
+    line_start: number;
+    metadata: Record<string, string>;
+    tag_lines: number[];
+    value_lines: string[];
+};
+export type OpenFence = {
+    character: string;
+    lang: string;
+    length: number;
+};
+export type TaggedBlockScannerState = {
+    blocks: TaggedFencedBlock[];
+    body_start: number;
+    heading_path: string[];
+    open_fence: OpenFence | null;
+    open_tagged_block: OpenTaggedBlock | null;
+    pending_tag_set: PendingTagSet | null;
+    title: string;
+};
+import type { TaggedFencedBlocksInput } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlockFile } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlock } from './tagged-fenced-blocks.types.ts';

package/lib/tagged-fenced-blocks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Tagged fenced block public API.
+ *
+ * Loads or extracts one markdown file worth of tagged fenced blocks and
+ * provides exact-match selection helpers.
+ *
+ * Kind: parse
+ * Status: active
+ * Tracked in: ../docs/plans/v0/tagged-fenced-block-extraction.md
+ * Decided by: ../docs/decisions/tagged-fenced-block-extraction.md
+ * @patram
+ * @see {@link ../docs/decisions/tagged-fenced-block-extraction.md}
+ */
+/**
+ * @param {TaggedFencedBlocksInput} input
+ * @returns {TaggedFencedBlockFile}
+ */
+export function extractTaggedFencedBlocks(input: TaggedFencedBlocksInput): TaggedFencedBlockFile;
+/**
+ * @param {string} file_path
+ * @returns {Promise<TaggedFencedBlockFile>}
+ */
+export function loadTaggedFencedBlocks(file_path: string): Promise<TaggedFencedBlockFile>;
+/**
+ * @param {TaggedFencedBlock[]} blocks
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {TaggedFencedBlock[]}
+ */
+export function selectTaggedBlocks(blocks: TaggedFencedBlock[], criteria: TaggedFencedBlockCriteria): TaggedFencedBlock[];
+/**
+ * @param {TaggedFencedBlock[]} blocks
+ * @param {TaggedFencedBlockCriteria} criteria
+ * @returns {TaggedFencedBlock}
+ */
+export function selectTaggedBlock(blocks: TaggedFencedBlock[], criteria: TaggedFencedBlockCriteria): TaggedFencedBlock;
+import type { TaggedFencedBlocksInput } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlockFile } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlock } from './tagged-fenced-blocks.types.ts';
+import type { TaggedFencedBlockCriteria } from './tagged-fenced-blocks.types.ts';

package/lib/tagged-fenced-blocks.types.d.ts

@@ -0,0 +1,32 @@
+export interface TaggedFencedBlocksInput {
+    file_path: string;
+    source_text: string;
+}
+export interface TaggedFencedBlockCriteria {
+    [key: string]: string;
+}
+export interface TaggedFencedBlockOrigin {
+    path: string;
+    line_start: number;
+    line_end: number;
+    tag_lines: number[];
+}
+export interface TaggedFencedBlockContext {
+    heading_path: string[];
+}
+export interface TaggedFencedBlock {
+    id: string;
+    lang: string;
+    value: string;
+    metadata: Record<string, string>;
+    origin: TaggedFencedBlockOrigin;
+    context: TaggedFencedBlockContext;
+}
+export interface TaggedFencedBlockFile {
+    path: string;
+    title: string;
+    blocks: TaggedFencedBlock[];
+}
+export interface TaggedFencedBlockError extends Error {
+    code: string;
+}

package/package.json

@@ -1,18 +1,27 @@
 {
   "name": "patram",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "type": "module",
   "main": "./lib/patram.js",
+  "types": "./lib/patram.d.ts",
   "exports": {
-    ".": "./lib/patram.js",
+    ".": {
+      "types": "./lib/patram.d.ts",
+      "default": "./lib/patram.js"
+    },
     "./bin/patram.js": "./bin/patram.js"
   },
   "files": [
     "bin/patram.js",
+    "lib/**/*.d.ts",
     "lib/**/*.js",
     "lib/**/*.ts",
+    "!bin/**/*.test.d.ts",
+    "!bin/**/*.test-helpers.d.ts",
     "!bin/**/*.test.js",
     "!bin/**/*.test-helpers.js",
+    "!lib/**/*.test.d.ts",
+    "!lib/**/*.test-helpers.d.ts",
     "!lib/**/*.test.js",
     "!lib/**/*.test-helpers.js"
   ],
@@ -37,6 +46,8 @@
     "check:staged": "lint-staged",
     "check:types": "tsc",
     "postversion": "git push && git push --tags",
+    "postpack": "node scripts/clean-package-api-declarations.js",
+    "prepack": "node scripts/build-package-api-declarations.js",
     "preversion": "npm run all",
     "prepare": "husky",
     "test": "vitest run",