patram 0.1.1 → 0.3.0

package/lib/resolve-patram-graph-config.js

@@ -21,7 +21,7 @@ import { parsePatramConfig } from './patram-config.js';
  */
 
 const BUILT_IN_PATRAM_CONFIG = {
-  kinds: {
+  classes: {
     document: {
       builtin: true,
       label: 'Document',
@@ -30,28 +30,28 @@ const BUILT_IN_PATRAM_CONFIG = {
   mappings: {
     'document.title': {
       node: {
+        class: 'document',
         field: 'title',
-        kind: 'document',
       },
     },
     'document.description': {
       node: {
+        class: 'document',
         field: 'description',
-        kind: 'document',
       },
     },
     'jsdoc.link': {
       emit: {
         relation: 'links_to',
         target: 'path',
-        target_kind: 'document',
+        target_class: 'document',
       },
     },
     'markdown.link': {
       emit: {
         relation: 'links_to',
         target: 'path',
-        target_kind: 'document',
+        target_class: 'document',
       },
     },
   },
@@ -71,10 +71,10 @@ const BUILT_IN_PATRAM_CONFIG = {
  * @returns {PatramConfig}
  */
 export function resolvePatramGraphConfig(repo_config) {
-  return parsePatramConfig({
-    kinds: {
-      ...BUILT_IN_PATRAM_CONFIG.kinds,
-      ...repo_config.kinds,
+  const graph_config = parsePatramConfig({
+    classes: {
+      ...BUILT_IN_PATRAM_CONFIG.classes,
+      ...repo_config.classes,
     },
     mappings: {
       ...BUILT_IN_PATRAM_CONFIG.mappings,
@@ -85,4 +85,10 @@ export function resolvePatramGraphConfig(repo_config) {
       ...repo_config.relations,
     },
   });
+
+  return {
+    ...graph_config,
+    class_schemas: repo_config.class_schemas,
+    fields: repo_config.fields,
+  };
 }

package/lib/resolve-where-clause.js

@@ -2,12 +2,16 @@
  * @import { PatramRepoConfig } from './load-patram-config.types.ts';
  */
 
+/**
+ * @typedef {{ kind: 'ad_hoc' } | { kind: 'stored_query', name: string }} QuerySource
+ */
+
 /**
  * Resolve an ad hoc or stored query into a where clause.
  *
  * @param {PatramRepoConfig} repo_config
  * @param {string[]} command_arguments
- * @returns {{ success: true, value: string } | { success: false, message: string }}
+ * @returns {{ success: true, value: { query_source: QuerySource, where_clause: string } } | { success: false, message: string }}
  */
 export function resolveWhereClause(repo_config, command_arguments) {
   if (command_arguments[0] === '--where') {
@@ -22,7 +26,12 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
     return {
       success: true,
-      value: where_clause,
+      value: {
+        query_source: {
+          kind: 'ad_hoc',
+        },
+        where_clause,
+      },
     };
   }
 
@@ -46,6 +55,12 @@ export function resolveWhereClause(repo_config, command_arguments) {
 
   return {
     success: true,
-    value: stored_query.where,
+    value: {
+      query_source: {
+        kind: 'stored_query',
+        name: stored_query_name,
+      },
+      where_clause: stored_query.where,
+    },
   };
 }

package/lib/show-document.js

@@ -212,17 +212,15 @@ function createResolvedLinkSummary(
     claim_value.target,
   );
   const target_node = graph_nodes[`doc:${target_path}`];
-  const target_title = target_node?.title ?? claim_value.text;
 
   return {
     label: claim_value.text,
     reference,
-    target: {
-      kind: target_node?.kind,
-      path: target_node?.path ?? target_path,
-      status: target_node?.status,
-      title: target_title,
-    },
+    target: createResolvedLinkTarget(
+      target_node,
+      target_path,
+      claim_value.text,
+    ),
   };
 }
 
@@ -239,6 +237,52 @@ function resolveShowTargetPath(source_file_path, raw_target) {
   return normalizeRepoRelativePath(posix.join(source_directory, raw_target));
 }
 
+/**
+ * @param {string | string[] | undefined} field_value
+ * @returns {string | undefined}
+ */
+function getScalarGraphField(field_value) {
+  if (Array.isArray(field_value)) {
+    return field_value[0];
+  }
+
+  return field_value;
+}
+
+/**
+ * @param {GraphNode | undefined} target_node
+ * @param {string} target_path
+ * @param {string} fallback_title
+ * @returns {{ kind?: string, path: string, status?: string, title: string }}
+ */
+function createResolvedLinkTarget(target_node, target_path, fallback_title) {
+  return {
+    kind: getResolvedLinkTargetKind(target_node),
+    path: getResolvedLinkTargetPath(target_node, target_path),
+    status: getScalarGraphField(target_node?.status),
+    title: getScalarGraphField(target_node?.title) ?? fallback_title,
+  };
+}
+
+/**
+ * @param {GraphNode | undefined} target_node
+ * @returns {string | undefined}
+ */
+function getResolvedLinkTargetKind(target_node) {
+  return getScalarGraphField(target_node?.$class ?? target_node?.kind);
+}
+
+/**
+ * @param {GraphNode | undefined} target_node
+ * @param {string} target_path
+ * @returns {string}
+ */
+function getResolvedLinkTargetPath(target_node, target_path) {
+  return (
+    getScalarGraphField(target_node?.$path ?? target_node?.path) ?? target_path
+  );
+}
+
 /**
  * @param {PatramClaim} claim
  * @returns {claim is PatramClaim & { type: 'markdown.link', value: { target: string, text: string } }}

package/lib/tagged-fenced-block-error.js

@@ -0,0 +1,17 @@
+/**
+ * @import { TaggedFencedBlockError } from './tagged-fenced-blocks.types.ts';
+ */
+
+/**
+ * @param {string} code
+ * @param {string} message
+ * @returns {TaggedFencedBlockError}
+ */
+export function createTaggedFencedBlockError(code, message) {
+  const error = /** @type {TaggedFencedBlockError} */ (new Error(message));
+
+  error.code = code;
+  error.name = 'TaggedFencedBlockError';
+
+  return error;
+}

package/lib/tagged-fenced-block-markdown.js

@@ -0,0 +1,111 @@
+const FRONT_MATTER_BOUNDARY_PATTERN = /^---$/du;
+const HEADING_PATTERN = /^(#{1,6})\s+(.+?)(?:\s+#+\s*)?$/du;
+const MARKDOWN_FENCE_PATTERN = /^([`~]{3,})(.*)$/du;
+
+/**
+ * @param {string[]} lines
+ * @returns {number}
+ */
+export function findMarkdownBodyStartLineIndex(lines) {
+  if (lines[0] !== '---') {
+    return 0;
+  }
+
+  for (let line_index = 1; line_index < lines.length; line_index += 1) {
+    if (FRONT_MATTER_BOUNDARY_PATTERN.test(lines[line_index])) {
+      return line_index + 1;
+    }
+  }
+
+  return 0;
+}
+
+/**
+ * @param {string[]} lines
+ * @param {number} body_start
+ * @returns {string}
+ */
+export function getMarkdownTitle(lines, body_start) {
+  const title_line = lines[body_start];
+
+  if (title_line === undefined) {
+    return '';
+  }
+
+  const trimmed_line = title_line.trim();
+
+  if (trimmed_line.length === 0) {
+    return '';
+  }
+
+  return parseHeading(trimmed_line)?.text ?? trimmed_line;
+}
+
+/**
+ * @param {string} line
+ * @returns {{ level: number, text: string } | null}
+ */
+export function parseHeading(line) {
+  const heading_match = line.trim().match(HEADING_PATTERN);
+
+  if (!heading_match) {
+    return null;
+  }
+
+  return {
+    level: heading_match[1].length,
+    text: heading_match[2].trim(),
+  };
+}
+
+/**
+ * @param {string[]} heading_path
+ * @param {string} title
+ * @param {{ level: number, text: string }} heading
+ * @returns {string[]}
+ */
+export function updateHeadingPath(heading_path, title, heading) {
+  if (heading.level === 1) {
+    return [heading.text];
+  }
+
+  const next_heading_path = heading_path.slice(0, heading.level - 1);
+
+  if (next_heading_path.length === 0 && title.length > 0) {
+    next_heading_path.push(title);
+  }
+
+  next_heading_path.push(heading.text);
+
+  return next_heading_path;
+}
+
+/**
+ * @param {string} line
+ * @returns {{ character: string, lang: string, length: number } | null}
+ */
+export function parseOpeningMarkdownFence(line) {
+  const trimmed_line = line.trimStart();
+  const fence_match = trimmed_line.match(MARKDOWN_FENCE_PATTERN);
+
+  if (!fence_match) {
+    return null;
+  }
+
+  return {
+    character: fence_match[1][0],
+    lang: fence_match[2].trim(),
+    length: fence_match[1].length,
+  };
+}
+
+/**
+ * @param {string} line
+ * @param {{ character: string, length: number }} open_fence
+ * @returns {boolean}
+ */
+export function isClosingMarkdownFence(line, open_fence) {
+  return line
+    .trimStart()
+    .startsWith(open_fence.character.repeat(open_fence.length));
+}

package/lib/tagged-fenced-block-metadata.js

@@ -0,0 +1,97 @@
+import { createTaggedFencedBlockError } from './tagged-fenced-block-error.js';
+
+const TAGGED_METADATA_LINE_PATTERN = /^\[patram\s+(.+)\]:\s*#\s*$/du;
+const TAGGED_METADATA_PAIR_PATTERN = /^([a-z][a-z0-9_]*)=([^\s]+)$/du;
+
+/**
+ * @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, pending_tag_set, next_tag_set) {
+  /** @type {Record<string, string>} */
+  const metadata = { ...pending_tag_set.metadata };
+
+  for (const [key, value] of Object.entries(next_tag_set.metadata)) {
+    if (metadata[key] !== undefined) {
+      throw createTaggedFencedBlockError(
+        'tagged_fenced_blocks.duplicate_metadata_key',
+        `Duplicate tagged metadata key "${key}" in "${file_path}" at line ${next_tag_set.tag_lines[0]}.`,
+      );
+    }
+
+    metadata[key] = value;
+  }
+
+  return {
+    metadata,
+    tag_lines: [...pending_tag_set.tag_lines, ...next_tag_set.tag_lines],
+  };
+}
+
+/**
+ * @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, line, line_number) {
+  const trimmed_line = line.trim();
+
+  if (!trimmed_line.startsWith('[patram')) {
+    return null;
+  }
+
+  const metadata_match = trimmed_line.match(TAGGED_METADATA_LINE_PATTERN);
+
+  if (!metadata_match) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.invalid_tag_line',
+      `Invalid tagged metadata line in "${file_path}" at line ${line_number}.`,
+    );
+  }
+
+  return {
+    metadata: parseTaggedMetadataPairs(
+      file_path,
+      metadata_match[1],
+      line_number,
+    ),
+    tag_lines: [line_number],
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {string} pair_text
+ * @param {number} line_number
+ * @returns {Record<string, string>}
+ */
+function parseTaggedMetadataPairs(file_path, pair_text, line_number) {
+  const tokens = pair_text.split(/\s+/du);
+  /** @type {Record<string, string>} */
+  const metadata = {};
+
+  for (const token of tokens) {
+    const pair_match = token.match(TAGGED_METADATA_PAIR_PATTERN);
+
+    if (!pair_match) {
+      throw createTaggedFencedBlockError(
+        'tagged_fenced_blocks.invalid_tag_line',
+        `Invalid tagged metadata line in "${file_path}" at line ${line_number}.`,
+      );
+    }
+
+    if (metadata[pair_match[1]] !== undefined) {
+      throw createTaggedFencedBlockError(
+        'tagged_fenced_blocks.duplicate_metadata_key',
+        `Duplicate tagged metadata key "${pair_match[1]}" in "${file_path}" at line ${line_number}.`,
+      );
+    }
+
+    metadata[pair_match[1]] = pair_match[2];
+  }
+
+  return metadata;
+}

package/lib/tagged-fenced-block-parser.js

@@ -0,0 +1,292 @@
+/**
+ * @import {
+ *   TaggedFencedBlock,
+ *   TaggedFencedBlockFile,
+ *   TaggedFencedBlocksInput,
+ * } from './tagged-fenced-blocks.types.ts';
+ */
+
+import {
+  findMarkdownBodyStartLineIndex,
+  getMarkdownTitle,
+  isClosingMarkdownFence,
+  parseHeading,
+  parseOpeningMarkdownFence,
+  updateHeadingPath,
+} from './tagged-fenced-block-markdown.js';
+import {
+  mergePendingTagSets,
+  parseTaggedMetadataLine,
+} from './tagged-fenced-block-metadata.js';
+import { createTaggedFencedBlockError } from './tagged-fenced-block-error.js';
+
+const BLANK_LINE_PATTERN = /^\s*$/du;
+
+/**
+ * @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) {
+  const lines = input.source_text.split('\n');
+  const state = createScannerState(lines);
+
+  for (const [line_index, line] of lines.entries()) {
+    if (line_index < state.body_start) {
+      continue;
+    }
+
+    scanMarkdownLine(input.file_path, state, line, line_index + 1);
+  }
+
+  finalizeScannerState(input.file_path, state);
+
+  return {
+    blocks: state.blocks,
+    path: input.file_path,
+    title: state.title,
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {TaggedBlockScannerState} state
+ * @param {string} line
+ * @param {number} line_number
+ */
+function scanMarkdownLine(file_path, state, line, line_number) {
+  if (state.open_fence) {
+    scanOpenFenceLine(file_path, state, line, line_number);
+    return;
+  }
+
+  if (tryOpenFence(state, line, line_number)) {
+    return;
+  }
+
+  if (state.pending_tag_set) {
+    scanPendingTagSetLine(file_path, state, line, line_number);
+    return;
+  }
+
+  const next_tag_set = parseTaggedMetadataLine(file_path, line, line_number);
+
+  if (next_tag_set) {
+    state.pending_tag_set = next_tag_set;
+    return;
+  }
+
+  const heading = parseHeading(line);
+
+  if (heading) {
+    state.heading_path = updateHeadingPath(
+      state.heading_path,
+      state.title,
+      heading,
+    );
+  }
+}
+
+/**
+ * @param {string} file_path
+ * @param {TaggedBlockScannerState} state
+ * @param {string} line
+ * @param {number} line_number
+ */
+function scanOpenFenceLine(file_path, state, line, line_number) {
+  if (!state.open_fence) {
+    return;
+  }
+
+  if (isClosingMarkdownFence(line, state.open_fence)) {
+    if (state.open_tagged_block) {
+      state.blocks.push(
+        createTaggedBlock(file_path, line_number, state.open_tagged_block),
+      );
+    }
+
+    state.open_fence = null;
+    state.open_tagged_block = null;
+    return;
+  }
+
+  if (state.open_tagged_block) {
+    state.open_tagged_block.value_lines.push(line);
+  }
+}
+
+/**
+ * @param {TaggedBlockScannerState} state
+ * @param {string} line
+ * @param {number} line_number
+ * @returns {boolean}
+ */
+function tryOpenFence(state, line, line_number) {
+  const open_fence = parseOpeningMarkdownFence(line);
+
+  if (!open_fence) {
+    return false;
+  }
+
+  state.open_fence = open_fence;
+  state.open_tagged_block = createOpenTaggedBlock(
+    line_number,
+    open_fence.lang,
+    state.pending_tag_set,
+    state.heading_path,
+  );
+  state.pending_tag_set = null;
+
+  return true;
+}
+
+/**
+ * @param {string} file_path
+ * @param {TaggedBlockScannerState} state
+ * @param {string} line
+ * @param {number} line_number
+ */
+function scanPendingTagSetLine(file_path, state, line, line_number) {
+  if (!state.pending_tag_set) {
+    return;
+  }
+
+  if (BLANK_LINE_PATTERN.test(line)) {
+    return;
+  }
+
+  const next_tag_set = parseTaggedMetadataLine(file_path, line, line_number);
+
+  if (!next_tag_set) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.unattached_tag_set',
+      `Tagged metadata in "${file_path}" at lines ${state.pending_tag_set.tag_lines.join(', ')} must attach directly to the next fenced block.`,
+    );
+  }
+
+  state.pending_tag_set = mergePendingTagSets(
+    file_path,
+    state.pending_tag_set,
+    next_tag_set,
+  );
+}
+
+/**
+ * @param {string[]} lines
+ * @returns {TaggedBlockScannerState}
+ */
+function createScannerState(lines) {
+  const body_start = findMarkdownBodyStartLineIndex(lines);
+  const title = getMarkdownTitle(lines, body_start);
+
+  return {
+    blocks: [],
+    body_start,
+    heading_path: title.length > 0 ? [title] : [],
+    open_fence: null,
+    open_tagged_block: null,
+    pending_tag_set: null,
+    title,
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {TaggedBlockScannerState} state
+ */
+function finalizeScannerState(file_path, state) {
+  if (state.open_tagged_block) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.unclosed_fence',
+      `Unclosed tagged fenced block in "${file_path}" starting at line ${state.open_tagged_block.line_start}.`,
+    );
+  }
+
+  if (state.pending_tag_set) {
+    throw createTaggedFencedBlockError(
+      'tagged_fenced_blocks.dangling_tag_set',
+      `Dangling tagged metadata in "${file_path}" at lines ${state.pending_tag_set.tag_lines.join(', ')}.`,
+    );
+  }
+}
+
+/**
+ * @param {number} line_number
+ * @param {string} lang
+ * @param {PendingTagSet | null} pending_tag_set
+ * @param {string[]} heading_path
+ * @returns {OpenTaggedBlock | null}
+ */
+function createOpenTaggedBlock(
+  line_number,
+  lang,
+  pending_tag_set,
+  heading_path,
+) {
+  if (!pending_tag_set) {
+    return null;
+  }
+
+  return {
+    heading_path: [...heading_path],
+    lang,
+    line_start: line_number,
+    metadata: { ...pending_tag_set.metadata },
+    tag_lines: [...pending_tag_set.tag_lines],
+    value_lines: [],
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @param {number} line_end
+ * @param {OpenTaggedBlock} open_tagged_block
+ * @returns {TaggedFencedBlock}
+ */
+function createTaggedBlock(file_path, line_end, open_tagged_block) {
+  return {
+    context: {
+      heading_path: [...open_tagged_block.heading_path],
+    },
+    id: `block:${file_path}:${open_tagged_block.line_start}`,
+    lang: open_tagged_block.lang,
+    metadata: { ...open_tagged_block.metadata },
+    origin: {
+      line_end,
+      line_start: open_tagged_block.line_start,
+      path: file_path,
+      tag_lines: [...open_tagged_block.tag_lines],
+    },
+    value: open_tagged_block.value_lines.join('\n'),
+  };
+}