patram 0.0.2 → 0.2.0

package/lib/resolve-check-target.js

@@ -0,0 +1,190 @@
+/**
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ */
+import { access, stat } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import process from 'node:process';
+
+const CONFIG_FILE_NAME = '.patram.json';
+
+/**
+ * @typedef {(
+ *   | { project_directory: string, target_kind: 'project' }
+ *   | { project_directory: string, target_kind: 'directory', target_path: string }
+ *   | { project_directory: string, target_kind: 'file', target_path: string }
+ * )} ResolvedCheckTarget
+ */
+
+/**
+ * Resolve the project directory and target scope for `check`.
+ *
+ * @param {string | undefined} target_argument
+ * @returns {Promise<ResolvedCheckTarget>}
+ */
+export async function resolveCheckTarget(target_argument) {
+  if (target_argument === undefined) {
+    return {
+      project_directory: process.cwd(),
+      target_kind: 'project',
+    };
+  }
+
+  const absolute_target_path = resolve(process.cwd(), target_argument);
+  const target_stats = await stat(absolute_target_path);
+  const target_directory = target_stats.isDirectory()
+    ? absolute_target_path
+    : dirname(absolute_target_path);
+  const project_directory = await findProjectDirectory(target_directory);
+
+  if (target_stats.isFile()) {
+    const target_path = normalizeRepoRelativePath(
+      relative(project_directory, absolute_target_path),
+    );
+
+    return {
+      project_directory,
+      target_kind: 'file',
+      target_path,
+    };
+  }
+
+  const target_path = normalizeRepoRelativePath(
+    relative(project_directory, absolute_target_path),
+  );
+
+  if (target_path.length === 0) {
+    return {
+      project_directory,
+      target_kind: 'project',
+    };
+  }
+
+  return {
+    project_directory,
+    target_kind: 'directory',
+    target_path,
+  };
+}
+
+/**
+ * Select the source files covered by one resolved `check` target.
+ *
+ * @param {string[]} source_file_paths
+ * @param {ResolvedCheckTarget} resolved_target
+ * @returns {string[]}
+ */
+export function selectCheckTargetSourceFiles(
+  source_file_paths,
+  resolved_target,
+) {
+  if (resolved_target.target_kind === 'project') {
+    return source_file_paths;
+  }
+
+  if (resolved_target.target_kind === 'file') {
+    return source_file_paths.filter(
+      (source_file_path) => source_file_path === resolved_target.target_path,
+    );
+  }
+
+  return source_file_paths.filter((source_file_path) =>
+    isPathInsideDirectory(source_file_path, resolved_target.target_path),
+  );
+}
+
+/**
+ * Filter diagnostics to one resolved `check` target.
+ *
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {ResolvedCheckTarget} resolved_target
+ * @returns {PatramDiagnostic[]}
+ */
+export function selectCheckTargetDiagnostics(diagnostics, resolved_target) {
+  if (resolved_target.target_kind === 'project') {
+    return diagnostics;
+  }
+
+  if (resolved_target.target_kind === 'file') {
+    return diagnostics.filter(
+      (diagnostic) => diagnostic.path === resolved_target.target_path,
+    );
+  }
+
+  return diagnostics.filter((diagnostic) =>
+    isPathInsideDirectory(diagnostic.path, resolved_target.target_path),
+  );
+}
+
+/**
+ * @param {string} start_directory
+ * @returns {Promise<string>}
+ */
+async function findProjectDirectory(start_directory) {
+  let current_directory = start_directory;
+
+  while (true) {
+    if (await hasConfigFile(current_directory)) {
+      return current_directory;
+    }
+
+    const parent_directory = dirname(current_directory);
+
+    if (parent_directory === current_directory) {
+      return start_directory;
+    }
+
+    current_directory = parent_directory;
+  }
+}
+
+/**
+ * @param {string} directory_path
+ * @returns {Promise<boolean>}
+ */
+async function hasConfigFile(directory_path) {
+  try {
+    await access(resolve(directory_path, CONFIG_FILE_NAME));
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      return false;
+    }
+
+    throw error;
+  }
+
+  return true;
+}
+
+/**
+ * @param {string} source_path
+ * @param {string} directory_path
+ * @returns {boolean}
+ */
+function isPathInsideDirectory(source_path, directory_path) {
+  return (
+    source_path === directory_path ||
+    source_path.startsWith(`${directory_path}/`)
+  );
+}
+
+/**
+ * @param {string} source_path
+ * @returns {string}
+ */
+function normalizeRepoRelativePath(source_path) {
+  return source_path.replaceAll('\\', '/');
+}
+
+/**
+ * @param {unknown} error
+ * @returns {error is NodeJS.ErrnoException}
+ */
+function isMissingPathError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return (
+    'code' in error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')
+  );
+}

package/lib/resolve-output-mode.js

@@ -0,0 +1,60 @@
+/**
+ * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
+ * @import { ResolvedOutputMode } from './output-view.types.ts';
+ */
+
+/**
+ * Resolve the renderer and color support for one command invocation.
+ *
+ * @param {ParsedCliArguments} parsed_arguments
+ * @param {{ is_tty: boolean, no_color: boolean, term: string | undefined }} output_context
+ * @returns {ResolvedOutputMode}
+ */
+export function resolveOutputMode(parsed_arguments, output_context) {
+  if (parsed_arguments.output_mode === 'json') {
+    return {
+      color_enabled: false,
+      renderer_name: 'json',
+    };
+  }
+
+  if (parsed_arguments.output_mode === 'plain') {
+    return {
+      color_enabled: false,
+      renderer_name: 'plain',
+    };
+  }
+
+  if (!output_context.is_tty) {
+    return {
+      color_enabled: false,
+      renderer_name: 'plain',
+    };
+  }
+
+  return {
+    color_enabled: isColorEnabled(parsed_arguments, output_context),
+    renderer_name: 'rich',
+  };
+}
+
+/**
+ * @param {ParsedCliArguments} parsed_arguments
+ * @param {{ is_tty: boolean, no_color: boolean, term: string | undefined }} output_context
+ * @returns {boolean}
+ */
+function isColorEnabled(parsed_arguments, output_context) {
+  if (parsed_arguments.color_mode === 'always') {
+    return true;
+  }
+
+  if (parsed_arguments.color_mode === 'never') {
+    return false;
+  }
+
+  if (output_context.no_color || output_context.term === 'dumb') {
+    return false;
+  }
+
+  return true;
+}

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

@@ -0,0 +1,88 @@
+/**
+ * @import { PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { PatramConfig } from './patram-config.types.ts';
+ */
+
+import { parsePatramConfig } from './patram-config.js';
+
+/**
+ * Built-in graph semantics.
+ *
+ * Merges repo-defined graph config with Patram's built-in document and link
+ * semantics before graph materialization.
+ *
+ * Kind: config
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/graph-materialization.md
+ * @patram
+ * @see {@link ./load-patram-config.js}
+ * @see {@link ../docs/graph-v0.md}
+ */
+
+const BUILT_IN_PATRAM_CONFIG = {
+  kinds: {
+    document: {
+      builtin: true,
+      label: 'Document',
+    },
+  },
+  mappings: {
+    'document.title': {
+      node: {
+        field: 'title',
+        kind: 'document',
+      },
+    },
+    'document.description': {
+      node: {
+        field: 'description',
+        kind: 'document',
+      },
+    },
+    'jsdoc.link': {
+      emit: {
+        relation: 'links_to',
+        target: 'path',
+        target_kind: 'document',
+      },
+    },
+    'markdown.link': {
+      emit: {
+        relation: 'links_to',
+        target: 'path',
+        target_kind: 'document',
+      },
+    },
+  },
+  relations: {
+    links_to: {
+      builtin: true,
+      from: ['document'],
+      to: ['document'],
+    },
+  },
+};
+
+/**
+ * Merge built-in Patram graph semantics with repo-defined schema.
+ *
+ * @param {PatramRepoConfig} repo_config
+ * @returns {PatramConfig}
+ */
+export function resolvePatramGraphConfig(repo_config) {
+  return parsePatramConfig({
+    kinds: {
+      ...BUILT_IN_PATRAM_CONFIG.kinds,
+      ...repo_config.kinds,
+    },
+    mappings: {
+      ...BUILT_IN_PATRAM_CONFIG.mappings,
+      ...repo_config.mappings,
+    },
+    relations: {
+      ...BUILT_IN_PATRAM_CONFIG.relations,
+      ...repo_config.relations,
+    },
+  });
+}

package/lib/resolve-where-clause.js

@@ -0,0 +1,66 @@
+/**
+ * @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: { query_source: QuerySource, where_clause: string } } | { success: false, message: string }}
+ */
+export function resolveWhereClause(repo_config, command_arguments) {
+  if (command_arguments[0] === '--where') {
+    const where_clause = command_arguments.slice(1).join(' ').trim();
+
+    if (where_clause.length === 0) {
+      return {
+        message: 'Query requires a where clause.',
+        success: false,
+      };
+    }
+
+    return {
+      success: true,
+      value: {
+        query_source: {
+          kind: 'ad_hoc',
+        },
+        where_clause,
+      },
+    };
+  }
+
+  const stored_query_name = command_arguments[0];
+
+  if (!stored_query_name) {
+    return {
+      message: 'Query requires "--where" or a stored query name.',
+      success: false,
+    };
+  }
+
+  const stored_query = repo_config.queries[stored_query_name];
+
+  if (!stored_query) {
+    return {
+      message: `Stored query "${stored_query_name}" was not found.`,
+      success: false,
+    };
+  }
+
+  return {
+    success: true,
+    value: {
+      query_source: {
+        kind: 'stored_query',
+        name: stored_query_name,
+      },
+      where_clause: stored_query.where,
+    },
+  };
+}

package/lib/show-document.js

@@ -0,0 +1,311 @@
+/* eslint-disable max-lines */
+/**
+ * @import { GraphNode } from './build-graph.types.ts';
+ * @import { PatramClaim } from './parse-claims.types.ts';
+ * @import { PatramDiagnostic } from './load-patram-config.types.ts';
+ */
+
+import { readFile } from 'node:fs/promises';
+import { posix, relative, resolve } from 'node:path';
+
+import { parseSourceFile } from './parse-claims.js';
+
+/**
+ * Show command document rendering.
+ *
+ * Loads one source file, resolves indexed links, and builds the shared show
+ * output model.
+ *
+ * Kind: output
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/show-output.md
+ * Decided by: ../docs/decisions/source-rendering.md
+ * @patram
+ * @see {@link ./render-output-view.js}
+ * @see {@link ../docs/decisions/show-output.md}
+ */
+
+/**
+ * @param {string} requested_file_path
+ * @param {string} project_directory
+ * @param {import('./build-graph.types.ts').BuildGraphResult} graph
+ * @returns {Promise<
+ *   | {
+ *       success: true;
+ *       value: {
+ *         path: string;
+ *         rendered_source: string;
+ *         resolved_links: Array<{
+ *           label: string;
+ *           reference: number;
+ *           target: { kind?: string, path: string, status?: string, title: string };
+ *         }>;
+ *         source: string;
+ *       };
+ *     }
+ *   | {
+ *       diagnostic: PatramDiagnostic;
+ *       success: false;
+ *     }
+ * >}
+ */
+export async function loadShowOutput(
+  requested_file_path,
+  project_directory,
+  graph,
+) {
+  const absolute_source_path = resolve(project_directory, requested_file_path);
+  const source_file_path = normalizeRepoRelativePath(
+    relative(project_directory, absolute_source_path),
+  );
+  let source_text;
+
+  try {
+    source_text = await readFile(absolute_source_path, 'utf8');
+  } catch (error) {
+    if (isFileNotFoundError(error)) {
+      return {
+        diagnostic: createShowFileNotFoundDiagnostic(source_file_path),
+        success: false,
+      };
+    }
+
+    throw error;
+  }
+
+  const parse_result = parseSourceFile({
+    path: source_file_path,
+    source: source_text,
+  });
+
+  if (parse_result.diagnostics.length > 0) {
+    return {
+      diagnostic: parse_result.diagnostics[0],
+      success: false,
+    };
+  }
+
+  return {
+    success: true,
+    value: createShowOutput(
+      source_file_path,
+      source_text,
+      parse_result.claims,
+      graph.nodes,
+    ),
+  };
+}
+
+/**
+ * @param {string} source_file_path
+ * @param {string} source_text
+ * @param {PatramClaim[]} claims
+ * @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 }}
+ */
+function createShowOutput(source_file_path, source_text, claims, graph_nodes) {
+  const link_claims = claims.filter(isResolvedLinkClaim);
+  const rendered_link_claims = link_claims.filter(isMarkdownLinkClaim);
+  const resolved_links = link_claims.map((claim, claim_index) =>
+    createResolvedLinkSummary(
+      source_file_path,
+      claim,
+      claim_index + 1,
+      graph_nodes,
+    ),
+  );
+
+  return {
+    path: source_file_path,
+    rendered_source: renderResolvedSource(
+      source_text,
+      rendered_link_claims,
+      resolved_links,
+    ),
+    resolved_links,
+    source: source_text,
+  };
+}
+
+/**
+ * @param {string} source_text
+ * @param {PatramClaim[]} link_claims
+ * @param {Array<{ label: string, reference: number }>} resolved_links
+ * @returns {string}
+ */
+function renderResolvedSource(source_text, link_claims, resolved_links) {
+  const source_lines = source_text.split('\n');
+
+  return trimTrailingLineBreaks(
+    source_lines
+      .map((source_line, line_index) =>
+        renderResolvedSourceLine(
+          source_line,
+          line_index + 1,
+          link_claims,
+          resolved_links,
+        ),
+      )
+      .join('\n'),
+  );
+}
+
+/**
+ * @param {string} source_line
+ * @param {number} line_number
+ * @param {PatramClaim[]} link_claims
+ * @param {Array<{ label: string, reference: number }>} resolved_links
+ * @returns {string}
+ */
+function renderResolvedSourceLine(
+  source_line,
+  line_number,
+  link_claims,
+  resolved_links,
+) {
+  const line_link_claims = link_claims.filter(
+    (claim) => claim.origin.line === line_number,
+  );
+
+  if (line_link_claims.length === 0) {
+    return source_line;
+  }
+
+  /** @type {string[]} */
+  const chunks = [];
+  let source_offset = 0;
+
+  for (const claim of line_link_claims) {
+    const claim_index = link_claims.indexOf(claim);
+    const claim_value = getLinkClaimValue(claim);
+    const rendered_link = resolved_links[claim_index];
+    const claim_column = claim.origin.column - 1;
+    const raw_link = `[${claim_value.text}](${claim_value.target})`;
+
+    chunks.push(source_line.slice(source_offset, claim_column));
+    chunks.push(`[${rendered_link.label}][${rendered_link.reference}]`);
+    source_offset = claim_column + raw_link.length;
+  }
+
+  chunks.push(source_line.slice(source_offset));
+
+  return chunks.join('');
+}
+
+/**
+ * @param {string} source_file_path
+ * @param {PatramClaim} claim
+ * @param {number} reference
+ * @param {Record<string, GraphNode>} graph_nodes
+ * @returns {{ label: string, reference: number, target: { kind?: string, path: string, status?: string, title: string } }}
+ */
+function createResolvedLinkSummary(
+  source_file_path,
+  claim,
+  reference,
+  graph_nodes,
+) {
+  const claim_value = getLinkClaimValue(claim);
+  const target_path = resolveShowTargetPath(
+    source_file_path,
+    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,
+    },
+  };
+}
+
+/**
+ * @param {string} source_file_path
+ * @param {string} raw_target
+ * @returns {string}
+ */
+function resolveShowTargetPath(source_file_path, raw_target) {
+  const source_directory = posix.dirname(
+    normalizeRepoRelativePath(source_file_path),
+  );
+
+  return normalizeRepoRelativePath(posix.join(source_directory, raw_target));
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @returns {claim is PatramClaim & { type: 'markdown.link', value: { target: string, text: string } }}
+ */
+function isMarkdownLinkClaim(claim) {
+  return claim.type === 'markdown.link';
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @returns {claim is PatramClaim & { type: 'jsdoc.link' | 'markdown.link', value: { target: string, text: string } }}
+ */
+function isResolvedLinkClaim(claim) {
+  return claim.type === 'markdown.link' || claim.type === 'jsdoc.link';
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @returns {{ target: string, text: string }}
+ */
+function getLinkClaimValue(claim) {
+  if (typeof claim.value === 'string') {
+    throw new Error(`Expected claim "${claim.id}" to carry a markdown link.`);
+  }
+
+  return claim.value;
+}
+
+/**
+ * @param {string} source_path
+ * @returns {string}
+ */
+function normalizeRepoRelativePath(source_path) {
+  return posix.normalize(source_path.replaceAll('\\', '/'));
+}
+
+/**
+ * @param {string} source_file_path
+ * @returns {PatramDiagnostic}
+ */
+function createShowFileNotFoundDiagnostic(source_file_path) {
+  return {
+    code: 'show.file_not_found',
+    column: 1,
+    level: 'error',
+    line: 1,
+    message: `File "${source_file_path}" was not found.`,
+    path: source_file_path,
+  };
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function trimTrailingLineBreaks(value) {
+  return value.replace(/\n+$/du, '');
+}
+
+/**
+ * @param {unknown} error
+ * @returns {error is NodeJS.ErrnoException}
+ */
+function isFileNotFoundError(error) {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  return 'code' in error && error.code === 'ENOENT';
+}