patram 0.8.0 → 0.10.0

package/lib/{render-output-view.js → output/view-model/index.js}

@@ -1,37 +1,18 @@
 /**
- * @import { BuildGraphResult, GraphNode } from './build-graph.types.ts';
- * @import { DerivedSummaryEvaluator } from './derived-summary.js';
- * @import { PatramRepoConfig } from './load-patram-config.types.ts';
- * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
- * @import { OutputDerivedSummary, OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, RefsOutputView, ResolvedOutputMode, ShowOutputView } from './output-view.types.ts';
+ * @import { BuildGraphResult, GraphNode } from '../../graph/build-graph.types.ts';
+ * @import { DerivedSummaryEvaluator } from '../derived-summary.js';
+ * @import { PatramRepoConfig } from '../../config/load-patram-config.types.ts';
+ * @import { OutputDerivedSummary, OutputMetadataField, OutputNodeItem, OutputResolvedLinkItem, OutputResolvedLinkTarget, OutputStoredQueryItem, OutputView, RefsOutputView, ShowOutputView } from '../output-view.types.ts';
  */
 /* eslint-disable max-lines */
 
-import { renderJsonOutput } from './render-json-output.js';
-import { renderPlainOutput } from './render-plain-output.js';
-import { renderRichOutput } from './render-rich-output.js';
-import { resolveDocumentNodeId } from './build-graph-identity.js';
-
-/**
- * Shared command output views.
- *
- * Normalizes `query`, `queries`, and `show` results into renderer-specific
- * output models.
- *
- * Kind: output
- * Status: active
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/cli-output-architecture.md
- * @patram
- * @see {@link ./show-document.js}
- * @see {@link ../docs/decisions/cli-output-architecture.md}
- */
+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}
  */
@@ -49,7 +30,7 @@ export function createOutputView(command_name, command_items, command_options) {
     );
   }
 
-  throw new Error(`Unsupported output view command "${command_name}".`);
+  throw new Error('Unsupported output view command.');
 }
 
 /**
@@ -60,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) =>
@@ -132,33 +98,6 @@ export function createRefsOutputView(refs_output, command_options = {}) {
   };
 }
 
-/**
- * Render one shared output view through the resolved renderer.
- *
- * @param {OutputView} output_view
- * @param {ResolvedOutputMode} output_mode
- * @param {ParsedCliArguments} parsed_arguments
- * @returns {Promise<string>}
- */
-export async function renderOutputView(
-  output_view,
-  output_mode,
-  parsed_arguments,
-) {
-  if (output_mode.renderer_name === 'json') {
-    return renderJsonOutput(output_view);
-  }
-
-  if (output_mode.renderer_name === 'plain') {
-    return renderPlainOutput(output_view);
-  }
-
-  return renderRichOutput(output_view, {
-    color_enabled: output_mode.color_enabled,
-    color_mode: parsed_arguments.color_mode,
-  });
-}
-
 /**
  * @param {GraphNode[]} graph_nodes
  * @param {{ derived_summary_evaluator?: DerivedSummaryEvaluator, hints?: string[], limit?: number, offset?: number, repo_config?: PatramRepoConfig, total_count?: number }=} command_options
@@ -190,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/{write-paged-output.js → output/write-paged-output.js}

@@ -42,10 +42,10 @@ async function writeOutputThroughPager(
 
   await writeToPagerInput(pager_process.stdin, output_text);
 
-  const [exit_code, signal_code] = await Promise.race([
-    close_promise,
-    error_promise,
-  ]);
+  const pager_result = /** @type {[number | null, NodeJS.Signals | null]} */ (
+    await Promise.race([close_promise, error_promise])
+  );
+  const [exit_code, signal_code] = pager_result;
 
   if (exit_code === 0) {
     return;
@@ -72,7 +72,11 @@ function writeToPagerInput(pager_input, output_text) {
         return;
       }
 
-      reject(error);
+      reject(
+        error instanceof Error
+          ? error
+          : new Error('Pager input failed with a non-Error rejection.'),
+      );
     });
     pager_input.end(output_text, 'utf8', resolve);
   });

package/lib/{claim-helpers.d.ts → parse/claim-helpers.d.ts}

@@ -16,5 +16,5 @@ export function createClaim(file_path: string, claim_number: number, claim_type:
  * @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';
+import type { PatramClaimFields } from './parse-claims.types.d.ts';
+import type { PatramClaim } from './parse-claims.types.d.ts';

package/lib/{parse-jsdoc-claims.d.ts → parse/jsdoc/parse-jsdoc-claims.d.ts}

@@ -5,5 +5,5 @@
  * @returns {ParseSourceFileResult}
  */
 export function parseJsdocClaims(parse_input: ParseClaimsInput): ParseSourceFileResult;
-import type { ParseClaimsInput } from './parse-claims.types.ts';
-import type { ParseSourceFileResult } from './parse-claims.types.ts';
+import type { ParseClaimsInput } from '../parse-claims.types.d.ts';
+import type { ParseSourceFileResult } from '../parse-claims.types.d.ts';

package/lib/{parse-jsdoc-claims.js → parse/jsdoc/parse-jsdoc-claims.js}

@@ -1,20 +1,20 @@
 /**
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
- * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaimFields } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic } from '../../config/load-patram-config.types.ts';
+ * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaimFields } from '../parse-claims.types.ts';
  */
 
 import {
   createClaim,
   getFileExtension,
   isPathLikeTarget,
-} from './claim-helpers.js';
-import { normalizeDirectiveName } from './parse-markdown-directives.js';
+} from '../claim-helpers.js';
+import { normalizeDirectiveName } from '../markdown/parse-markdown-directives.js';
 import { collectJsdocBlocks } from './parse-jsdoc-blocks.js';
 import {
   createJsdocProseClaimEntries,
   pushJsdocParagraph,
 } from './parse-jsdoc-prose.js';
-import { JSDOC_SOURCE_FILE_EXTENSIONS } from './source-file-defaults.js';
+import { JSDOC_SOURCE_FILE_EXTENSIONS } from '../../config/source-file-defaults.js';
 
 /**
  * JSDoc @patram claim parsing.
@@ -24,11 +24,11 @@ import { JSDOC_SOURCE_FILE_EXTENSIONS } from './source-file-defaults.js';
  *
  * Kind: parse
  * Status: active
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/jsdoc-metadata-directive-syntax.md
+ * Tracked in: ../../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../../docs/decisions/jsdoc-metadata-directive-syntax.md
  * @patram
- * @see {@link ./parse-claims.js}
- * @see {@link ../docs/decisions/jsdoc-metadata-directive-syntax.md}
+ * @see {@link ../parse-claims.js}
+ * @see {@link ../../../docs/decisions/jsdoc-metadata-directive-syntax.md}
  */
 
 const JSDOC_EXTENSIONS = new Set(JSDOC_SOURCE_FILE_EXTENSIONS);

package/lib/{parse-jsdoc-prose.d.ts → parse/jsdoc/parse-jsdoc-prose.d.ts}

@@ -25,4 +25,4 @@ export function createJsdocProseClaimEntries(file_path: string, prose_paragraphs
     claim_type: string;
     order: number;
 }>;
-import type { PatramClaimFields } from './parse-claims.types.ts';
+import type { PatramClaimFields } from '../parse-claims.types.d.ts';

package/lib/{parse-jsdoc-prose.js → parse/jsdoc/parse-jsdoc-prose.js}

@@ -1,5 +1,5 @@
 /**
- * @import { PatramClaimFields } from './parse-claims.types.ts';
+ * @import { PatramClaimFields } from '../parse-claims.types.ts';
  */
 
 const JSDOC_SENTENCE_PATTERN = /^(.+?[.!?])(?:\s+|$)([\s\S]*)$/du;

package/lib/{parse-markdown-claims.d.ts → parse/markdown/parse-markdown-claims.d.ts}

@@ -9,6 +9,6 @@ export function parseMarkdownClaims(parse_input: ParseClaimsInput, parse_options
     claims: PatramClaim[];
     diagnostics: PatramDiagnostic[];
 };
-import type { ParseClaimsInput } from './parse-claims.types.ts';
-import type { PatramClaim } from './parse-claims.types.ts';
-import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { ParseClaimsInput } from '../parse-claims.types.d.ts';
+import type { PatramClaim } from '../parse-claims.types.d.ts';
+import type { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';

package/lib/{parse-markdown-claims.js → parse/markdown/parse-markdown-claims.js}

@@ -1,9 +1,9 @@
 /**
- * @import { PatramClaim, ParseClaimsInput, PatramClaimFields } from './parse-claims.types.ts';
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { PatramClaim, ParseClaimsInput, PatramClaimFields } from '../parse-claims.types.ts';
+ * @import { PatramDiagnostic } from '../../config/load-patram-config.types.ts';
  */
 
-import { createClaim, isPathLikeTarget } from './claim-helpers.js';
+import { createClaim, isPathLikeTarget } from '../claim-helpers.js';
 import {
   matchHiddenDirectiveFields,
   matchVisibleDirectiveFields,
@@ -18,12 +18,12 @@ import {
  *
  * Kind: parse
  * Status: active
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/markdown-metadata-directive-syntax.md
- * Decided by: ../docs/decisions/markdown-link-claim-scope.md
+ * Tracked in: ../../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../../docs/decisions/markdown-metadata-directive-syntax.md
+ * Decided by: ../../../docs/decisions/markdown-link-claim-scope.md
  * @patram
- * @see {@link ./parse-claims.js}
- * @see {@link ../docs/decisions/markdown-metadata-directive-syntax.md}
+ * @see {@link ../parse-claims.js}
+ * @see {@link ../../../docs/decisions/markdown-metadata-directive-syntax.md}
  */
 
 const HEADING_PATTERN = /^#\s+(.+)$/du;

package/lib/{parse-markdown-directives.d.ts → parse/markdown/parse-markdown-directives.d.ts}

@@ -30,5 +30,5 @@ export function matchHiddenDirectiveFields(file_path: string, line: string, line
  * @returns {string}
  */
 export function normalizeDirectiveName(directive_label: string): string;
-import type { PatramDiagnostic } from './load-patram-config.types.ts';
-import type { PatramClaimFields } from './parse-claims.types.ts';
+import type { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';
+import type { PatramClaimFields } from '../parse-claims.types.d.ts';

package/lib/{parse-markdown-directives.js → parse/markdown/parse-markdown-directives.js}

@@ -1,9 +1,9 @@
 /**
- * @import { MarkdownDirectiveStyle, PatramClaimFields } from './parse-claims.types.ts';
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ * @import { MarkdownDirectiveStyle, PatramClaimFields } from '../parse-claims.types.ts';
+ * @import { PatramDiagnostic } from '../../config/load-patram-config.types.ts';
  */
 
-import { parseYamlDirectiveFields } from './parse-yaml-claims.js';
+import { parseYamlDirectiveFields } from '../yaml/parse-yaml-claims.js';
 
 const FRONT_MATTER_BOUNDARY_PATTERN = /^---$/du;
 const MARKDOWN_HIDDEN_DIRECTIVE_PATTERN =

package/lib/{parse-claims.d.ts → parse/parse-claims.d.ts}

@@ -8,16 +8,6 @@
 export function parseSourceFile(parse_input: ParseClaimsInput, parse_options?: {
     multi_value_directive_names?: ReadonlySet<string>;
 }): ParseSourceFileResult;
-/**
- * Parse a file into neutral Patram claims.
- *
- * @param {ParseClaimsInput} parse_input
- * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
- * @returns {PatramClaim[]}
- */
-export function parseClaims(parse_input: ParseClaimsInput, parse_options?: {
-    multi_value_directive_names?: ReadonlySet<string>;
-}): PatramClaim[];
 /**
  * Build parser options from repo config.
  *
@@ -35,6 +25,7 @@ export function createParseOptions(repo_config: {
 } | undefined): {
     multi_value_directive_names: Set<string>;
 };
-import type { ParseClaimsInput } from './parse-claims.types.ts';
-import type { ParseSourceFileResult } from './parse-claims.types.ts';
-import type { PatramClaim } from './parse-claims.types.ts';
+export type ClaimOrigin = import("./parse-claims.types.d.ts").ClaimOrigin;
+export type ParseClaimsInput = import("./parse-claims.types.d.ts").ParseClaimsInput;
+export type ParseSourceFileResult = import("./parse-claims.types.d.ts").ParseSourceFileResult;
+export type PatramClaim = import("./parse-claims.types.d.ts").PatramClaim;

package/lib/{parse-claims.js → parse/parse-claims.js}

@@ -1,15 +1,18 @@
-/**
- * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaim } from './parse-claims.types.ts';
- */
-
 import { getFileExtension } from './claim-helpers.js';
-import { parseJsdocClaims } from './parse-jsdoc-claims.js';
-import { parseMarkdownClaims } from './parse-markdown-claims.js';
-import { parseYamlClaims } from './parse-yaml-claims.js';
+import { parseJsdocClaims } from './jsdoc/parse-jsdoc-claims.js';
+import { parseMarkdownClaims } from './markdown/parse-markdown-claims.js';
+import { parseYamlClaims } from './yaml/parse-yaml-claims.js';
 import {
   MARKDOWN_SOURCE_FILE_EXTENSIONS,
   YAML_SOURCE_FILE_EXTENSIONS,
-} from './source-file-defaults.js';
+} from '../config/source-file-defaults.js';
+
+/**
+ * @typedef {import('./parse-claims.types.ts').ClaimOrigin} ClaimOrigin
+ * @typedef {import('./parse-claims.types.ts').ParseClaimsInput} ParseClaimsInput
+ * @typedef {import('./parse-claims.types.ts').ParseSourceFileResult} ParseSourceFileResult
+ * @typedef {import('./parse-claims.types.ts').PatramClaim} PatramClaim
+ */
 
 /**
  * Source claim dispatch.
@@ -19,14 +22,14 @@ import {
  *
  * Kind: parse
  * Status: active
- * Uses Term: ../docs/reference/terms/claim.md
- * Uses Term: ../docs/reference/terms/document.md
- * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
- * Decided by: ../docs/decisions/jsdoc-metadata-directive-syntax.md
- * Implements: ../docs/tasks/v0/parse-claims.md
+ * Uses Term: ../../docs/reference/terms/claim.md
+ * Uses Term: ../../docs/reference/terms/document.md
+ * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../../docs/decisions/jsdoc-metadata-directive-syntax.md
+ * Implements: ../../docs/tasks/v0/parse-claims.md
  * @patram
- * @see {@link ./parse-markdown-claims.js}
- * @see {@link ./parse-jsdoc-claims.js}
+ * @see {@link ./markdown/parse-markdown-claims.js}
+ * @see {@link ./jsdoc/parse-jsdoc-claims.js}
  */
 
 const MARKDOWN_EXTENSIONS = new Set(MARKDOWN_SOURCE_FILE_EXTENSIONS);
@@ -53,17 +56,6 @@ export function parseSourceFile(parse_input, parse_options) {
   return parseJsdocClaims(parse_input);
 }
 
-/**
- * Parse a file into neutral Patram claims.
- *
- * @param {ParseClaimsInput} parse_input
- * @param {{ multi_value_directive_names?: ReadonlySet<string> }} [parse_options]
- * @returns {PatramClaim[]}
- */
-export function parseClaims(parse_input, parse_options) {
-  return parseSourceFile(parse_input, parse_options).claims;
-}
-
 /**
  * Build parser options from repo config.
  *

package/lib/{parse-claims.types.d.ts → parse/parse-claims.types.d.ts}

@@ -1,4 +1,4 @@
-import type { PatramDiagnostic } from './load-patram-config.types.ts';
+import type { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';
 export type MarkdownDirectiveStyle = 'front_matter' | 'visible_line' | 'list_item' | 'hidden_tag';
 export interface ParseClaimsInput {
     path: string;

package/lib/{tagged-fenced-block-error.d.ts → parse/tagged-fenced/tagged-fenced-block-error.d.ts}

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

package/lib/{tagged-fenced-block-parser.d.ts → parse/tagged-fenced/tagged-fenced-block-parser.d.ts}

@@ -56,6 +56,6 @@ export type TaggedBlockScannerState = {
     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';
+import type { TaggedFencedBlocksInput } from './tagged-fenced-blocks.types.d.ts';
+import type { TaggedFencedBlockFile } from './tagged-fenced-blocks.types.d.ts';
+import type { TaggedFencedBlock } from './tagged-fenced-blocks.types.d.ts';

package/lib/{tagged-fenced-blocks.d.ts → parse/tagged-fenced/tagged-fenced-blocks.d.ts}

@@ -6,10 +6,10 @@
  *
  * Kind: parse
  * Status: active
- * Tracked in: ../docs/plans/v0/tagged-fenced-block-extraction.md
- * Decided by: ../docs/decisions/tagged-fenced-block-extraction.md
+ * 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}
+ * @see {@link ../../../docs/decisions/tagged-fenced-block-extraction.md}
  */
 /**
  * @param {TaggedFencedBlocksInput} input
@@ -33,7 +33,7 @@ export function selectTaggedBlocks(blocks: TaggedFencedBlock[], criteria: Tagged
  * @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';
+import type { TaggedFencedBlocksInput } from './tagged-fenced-blocks.types.d.ts';
+import type { TaggedFencedBlockFile } from './tagged-fenced-blocks.types.d.ts';
+import type { TaggedFencedBlock } from './tagged-fenced-blocks.types.d.ts';
+import type { TaggedFencedBlockCriteria } from './tagged-fenced-blocks.types.d.ts';

package/lib/{tagged-fenced-blocks.js → parse/tagged-fenced/tagged-fenced-blocks.js}

@@ -20,10 +20,10 @@ import { extractTaggedFencedBlocksFromSource } from './tagged-fenced-block-parse
  *
  * Kind: parse
  * Status: active
- * Tracked in: ../docs/plans/v0/tagged-fenced-block-extraction.md
- * Decided by: ../docs/decisions/tagged-fenced-block-extraction.md
+ * 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}
+ * @see {@link ../../../docs/decisions/tagged-fenced-block-extraction.md}
  */
 
 /**

package/lib/{parse-yaml-claims.d.ts → parse/yaml/parse-yaml-claims.d.ts}

@@ -32,7 +32,7 @@ export function parseYamlDirectiveFields(parse_input: {
     diagnostics: PatramDiagnostic[];
     directive_fields: PatramClaimFields[];
 };
-import type { ParseClaimsInput } from './parse-claims.types.ts';
-import type { ParseSourceFileResult } from './parse-claims.types.ts';
-import type { PatramDiagnostic } from './load-patram-config.types.ts';
-import type { PatramClaimFields } from './parse-claims.types.ts';
+import type { ParseClaimsInput } from '../parse-claims.types.d.ts';
+import type { ParseSourceFileResult } from '../parse-claims.types.d.ts';
+import type { PatramDiagnostic } from '../../config/load-patram-config.types.d.ts';
+import type { PatramClaimFields } from '../parse-claims.types.d.ts';

package/lib/{parse-yaml-claims.js → parse/yaml/parse-yaml-claims.js}

@@ -1,14 +1,14 @@
 /** @import * as yaml from 'yaml'; */
 /* eslint-disable max-lines */
 /**
- * @import { PatramDiagnostic } from './load-patram-config.types.ts';
- * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaimFields } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic } from '../../config/load-patram-config.types.ts';
+ * @import { ParseClaimsInput, ParseSourceFileResult, PatramClaimFields } from '../parse-claims.types.ts';
  */
 
 import { isMap, isScalar, isSeq, LineCounter, parseAllDocuments } from 'yaml';
 
-import { createClaim, getFileExtension } from './claim-helpers.js';
-import { YAML_SOURCE_FILE_EXTENSIONS } from './source-file-defaults.js';
+import { createClaim, getFileExtension } from '../claim-helpers.js';
+import { YAML_SOURCE_FILE_EXTENSIONS } from '../../config/source-file-defaults.js';
 
 /**
  * YAML claim parsing.
@@ -18,11 +18,11 @@ import { YAML_SOURCE_FILE_EXTENSIONS } from './source-file-defaults.js';
  *
  * Kind: parse
  * Status: active
- * Tracked in: ../docs/plans/v0/yaml-source-and-front-matter.md
- * Decided by: ../docs/decisions/yaml-source-and-front-matter.md
+ * Tracked in: ../../../docs/plans/v0/yaml-source-and-front-matter.md
+ * Decided by: ../../../docs/decisions/yaml-source-and-front-matter.md
  * @patram
- * @see {@link ./parse-claims.js}
- * @see {@link ./parse-markdown-directives.js}
+ * @see {@link ../parse-claims.js}
+ * @see {@link ../markdown/parse-markdown-directives.js}
  */
 
 const YAML_EXTENSIONS = new Set(YAML_SOURCE_FILE_EXTENSIONS);
@@ -107,7 +107,7 @@ export function parseYamlDirectiveFields(parse_input) {
  *   file_path: string,
  *   start_line: number,
  * }} parse_input
- * @param {any[]} yaml_documents
+ * @param {yaml.Document.Parsed[]} yaml_documents
  * @param {LineCounter} line_counter
  * @returns {{
   success: true,
@@ -221,12 +221,13 @@ function collectDirectiveFields(parse_input, yaml_map, line_counter) {
  *   markdown_style?: 'front_matter',
  *   multi_value_directive_names?: ReadonlySet<string>,
  * }} parse_input
- * @param {any} yaml_pair
+ * @param {yaml.Pair<unknown, unknown>} yaml_pair
  * @param {LineCounter} line_counter
  * @returns {PatramClaimFields[]}
  */
 function createPairDirectiveFields(parse_input, yaml_pair, line_counter) {
   const directive_name = resolveDirectiveName(yaml_pair.key);
+  const key_node = isNodeWithOptionalRange(yaml_pair.key) ? yaml_pair.key : {};
 
   if (!directive_name || yaml_pair.value === null) {
     return [];
@@ -236,7 +237,7 @@ function createPairDirectiveFields(parse_input, yaml_pair, line_counter) {
     return createScalarDirectiveFields(
       parse_input,
       directive_name,
-      yaml_pair.key,
+      key_node,
       yaml_pair.value.value,
       line_counter,
     );
@@ -303,7 +304,7 @@ function createScalarDirectiveFields(
  * }} parse_input
  * @param {string} directive_name
  * @param {unknown} yaml_value
- * @returns {boolean}
+ * @returns {yaml_value is yaml.YAMLSeq<yaml.Scalar<string | boolean | number>>}
  */
 function shouldCollectSequence(parse_input, directive_name, yaml_value) {
   return (
@@ -379,7 +380,15 @@ function normalizeScalarValue(scalar_value) {
 
 /**
  * @param {unknown} yaml_node
- * @returns {boolean}
+ * @returns {yaml_node is { range?: [number, number, number] }}
+ */
+function isNodeWithOptionalRange(yaml_node) {
+  return typeof yaml_node === 'object' && yaml_node !== null;
+}
+
+/**
+ * @param {unknown} yaml_node
+ * @returns {yaml_node is yaml.Scalar<string | boolean | number>}
  */
 function isNonNullScalarNode(yaml_node) {
   return isScalar(yaml_node) && normalizeScalarValue(yaml_node.value) !== null;