patram 0.0.2 → 0.1.1

package/lib/check-graph.js

@@ -3,17 +3,33 @@
  * @import { PatramDiagnostic } from './load-patram-config.types.ts';
  */
 
+/**
+ * Graph validation.
+ *
+ * Reports broken document links and missing edge nodes after graph
+ * materialization.
+ *
+ * Kind: graph
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/check-link-target-existence.md
+ * Implements: ../docs/tasks/v0/check-command.md
+ * @patram
+ * @see {@link ./build-graph.js}
+ * @see {@link ../docs/decisions/check-link-target-existence.md}
+ */
+
 /**
  * Check a materialized graph for broken document links and missing edge nodes.
  *
  * @param {BuildGraphResult} graph
- * @param {string[]} source_file_paths
+ * @param {string[]} existing_file_paths
  * @returns {PatramDiagnostic[]}
  */
-export function checkGraph(graph, source_file_paths) {
+export function checkGraph(graph, existing_file_paths) {
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
-  const source_file_path_set = new Set(source_file_paths);
+  const existing_file_path_set = new Set(existing_file_paths);
 
   for (const graph_edge of graph.edges) {
     const source_node = graph.nodes[graph_edge.from];
@@ -34,7 +50,7 @@ export function checkGraph(graph, source_file_paths) {
       diagnostics,
       graph_edge,
       target_node,
-      source_file_path_set,
+      existing_file_path_set,
     );
   }
 
@@ -78,13 +94,13 @@ function collectMissingNodeDiagnostics(
  * @param {PatramDiagnostic[]} diagnostics
  * @param {GraphEdge} graph_edge
  * @param {GraphNode} target_node
- * @param {Set<string>} source_file_path_set
+ * @param {Set<string>} existing_file_path_set
  */
 function collectBrokenLinkDiagnostics(
   diagnostics,
   graph_edge,
   target_node,
-  source_file_path_set,
+  existing_file_path_set,
 ) {
   if (graph_edge.relation !== 'links_to') {
     return;
@@ -94,7 +110,7 @@ function collectBrokenLinkDiagnostics(
     return;
   }
 
-  if (source_file_path_set.has(target_node.path)) {
+  if (existing_file_path_set.has(target_node.path)) {
     return;
   }
 

package/lib/claim-helpers.js

@@ -0,0 +1,55 @@
+/**
+ * @import { PatramClaim, PatramClaimFields } from './parse-claims.types.ts';
+ */
+
+const URI_SCHEME_PATTERN = /^[A-Za-z][A-Za-z0-9+.-]*:/du;
+
+/**
+ * @param {string} target_value
+ * @returns {boolean}
+ */
+export function isPathLikeTarget(target_value) {
+  if (target_value.startsWith('#')) {
+    return false;
+  }
+
+  return !URI_SCHEME_PATTERN.test(target_value);
+}
+
+/**
+ * @param {string} file_path
+ * @param {number} claim_number
+ * @param {string} claim_type
+ * @param {PatramClaimFields} claim_fields
+ * @returns {PatramClaim}
+ */
+export function createClaim(file_path, claim_number, claim_type, claim_fields) {
+  const document_id = `doc:${file_path}`;
+  const origin = claim_fields.origin ?? {
+    column: 1,
+    line: 1,
+    path: file_path,
+  };
+
+  return {
+    ...claim_fields,
+    document_id,
+    id: `claim:${document_id}:${claim_number}`,
+    origin,
+    type: claim_type,
+  };
+}
+
+/**
+ * @param {string} file_path
+ * @returns {string}
+ */
+export function getFileExtension(file_path) {
+  const last_dot_index = file_path.lastIndexOf('.');
+
+  if (last_dot_index < 0) {
+    return '';
+  }
+
+  return file_path.slice(last_dot_index);
+}

package/lib/command-output.js

@@ -0,0 +1,83 @@
+/**
+ * @import { ParsedCliArguments } from './parse-cli-arguments.types.ts';
+ * @import { OutputView } from './output-view.types.ts';
+ */
+
+import process from 'node:process';
+
+import { renderOutputView } from './render-output-view.js';
+import { resolveOutputMode } from './resolve-output-mode.js';
+import { writePagedOutput } from './write-paged-output.js';
+
+/**
+ * TTY and pager output control.
+ *
+ * Resolves the final output mode and switches between direct stdout writes and
+ * interactive pager output.
+ *
+ * Kind: output
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/tty-pager-output.md
+ * @patram
+ * @see {@link ./render-output-view.js}
+ * @see {@link ../docs/decisions/tty-pager-output.md}
+ */
+
+/**
+ * @param {{ stdout: { isTTY?: boolean, write(chunk: string): boolean }, write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @param {ParsedCliArguments} parsed_command
+ * @param {OutputView} output_view
+ * @returns {Promise<void>}
+ */
+export async function writeCommandOutput(
+  io_context,
+  parsed_command,
+  output_view,
+) {
+  const rendered_output = await renderOutputView(
+    output_view,
+    resolveOutputMode(parsed_command, {
+      is_tty: io_context.stdout.isTTY === true,
+      no_color: process.env.NO_COLOR !== undefined,
+      term: process.env.TERM,
+    }),
+    parsed_command,
+  );
+
+  if (shouldPageCommandOutput(parsed_command, io_context.stdout)) {
+    await writeInteractiveOutput(io_context, rendered_output);
+
+    return;
+  }
+
+  io_context.stdout.write(rendered_output);
+}
+
+/**
+ * @param {ParsedCliArguments} parsed_command
+ * @param {{ isTTY?: boolean }} output_stream
+ * @returns {boolean}
+ */
+export function shouldPageCommandOutput(parsed_command, output_stream) {
+  return (
+    output_stream.isTTY === true &&
+    (parsed_command.command_name === 'query' ||
+      parsed_command.command_name === 'show')
+  );
+}
+
+/**
+ * @param {{ write_paged_output?: (output_text: string) => Promise<void> }} io_context
+ * @param {string} rendered_output
+ * @returns {Promise<void>}
+ */
+async function writeInteractiveOutput(io_context, rendered_output) {
+  if (io_context.write_paged_output) {
+    await io_context.write_paged_output(rendered_output);
+
+    return;
+  }
+
+  await writePagedOutput(rendered_output);
+}

package/lib/layout-stored-queries.js

@@ -0,0 +1,213 @@
+/**
+ * @import { OutputStoredQueryItem } from './output-view.types.ts';
+ */
+
+import { parseWhereClause } from './parse-where-clause.js';
+
+const MAX_STORED_QUERY_WIDTH = 100;
+const MIN_TERM_COLUMN_WIDTH = 20;
+const STORED_QUERY_COLUMN_GAP = 2;
+
+/**
+ * @typedef {'field_name' | 'keyword' | 'literal' | 'name' | 'operator' | 'plain'} StoredQuerySegmentKind
+ */
+
+/**
+ * @typedef {{ kind: StoredQuerySegmentKind, text: string }} StoredQuerySegment
+ */
+
+/**
+ * Layout stored queries into styled lines shared by plain and rich renderers.
+ *
+ * @param {OutputStoredQueryItem[]} output_items
+ * @returns {StoredQuerySegment[][]}
+ */
+export function layoutStoredQueries(output_items) {
+  if (output_items.length === 0) {
+    return [];
+  }
+
+  const name_column_width = Math.max(
+    ...output_items.map((output_item) => output_item.name.length),
+  );
+  const term_column_width = Math.max(
+    MIN_TERM_COLUMN_WIDTH,
+    MAX_STORED_QUERY_WIDTH - name_column_width - STORED_QUERY_COLUMN_GAP,
+  );
+
+  return output_items.flatMap((output_item) =>
+    layoutStoredQuery(output_item, name_column_width, term_column_width),
+  );
+}
+
+/**
+ * @param {OutputStoredQueryItem} output_item
+ * @param {number} name_column_width
+ * @param {number} term_column_width
+ * @returns {StoredQuerySegment[][]}
+ */
+function layoutStoredQuery(output_item, name_column_width, term_column_width) {
+  const term_lines = wrapPhrases(
+    createStoredQueryPhrases(output_item.where),
+    term_column_width,
+  );
+  const continuation_prefix = ' '.repeat(
+    name_column_width + STORED_QUERY_COLUMN_GAP,
+  );
+
+  return term_lines.map((line_segments, line_index) => {
+    if (line_index === 0) {
+      return [
+        {
+          kind: 'name',
+          text: output_item.name.padEnd(name_column_width, ' '),
+        },
+        {
+          kind: 'plain',
+          text: ' '.repeat(STORED_QUERY_COLUMN_GAP),
+        },
+        ...line_segments,
+      ];
+    }
+
+    return [
+      {
+        kind: 'plain',
+        text: continuation_prefix,
+      },
+      ...line_segments,
+    ];
+  });
+}
+
+/**
+ * @param {string} where_clause
+ * @returns {StoredQuerySegment[][]}
+ */
+function createStoredQueryPhrases(where_clause) {
+  const parse_result = parseWhereClause(where_clause);
+
+  if (!parse_result.success) {
+    return createFallbackPhrases(where_clause);
+  }
+
+  return parse_result.clauses.map((clause, clause_index) =>
+    createClausePhrase(clause, clause_index > 0),
+  );
+}
+
+/**
+ * @param {{ is_negated: boolean, term: { kind: 'field', field_name: 'id' | 'kind' | 'path' | 'status' | 'title', operator: '=' | '^=' | '~', value: string } | { kind: 'relation', relation_name: string } | { kind: 'relation_target', relation_name: string, target_id: string } }} clause
+ * @param {boolean} should_prefix_and
+ * @returns {StoredQuerySegment[]}
+ */
+function createClausePhrase(clause, should_prefix_and) {
+  /** @type {StoredQuerySegment[]} */
+  const phrase = [];
+
+  if (should_prefix_and) {
+    phrase.push({ kind: 'keyword', text: 'and' });
+    phrase.push({ kind: 'plain', text: ' ' });
+  }
+
+  if (clause.is_negated) {
+    phrase.push({ kind: 'keyword', text: 'not' });
+    phrase.push({ kind: 'plain', text: ' ' });
+  }
+
+  phrase.push(...createTermSegments(clause.term));
+
+  return phrase;
+}
+
+/**
+ * @param {{ kind: 'field', field_name: 'id' | 'kind' | 'path' | 'status' | 'title', operator: '=' | '^=' | '~', value: string } | { kind: 'relation', relation_name: string } | { kind: 'relation_target', relation_name: string, target_id: string }} term
+ * @returns {StoredQuerySegment[]}
+ */
+function createTermSegments(term) {
+  if (term.kind === 'field') {
+    return [
+      { kind: 'field_name', text: term.field_name },
+      { kind: 'operator', text: term.operator },
+      { kind: 'literal', text: term.value },
+    ];
+  }
+
+  if (term.kind === 'relation_target') {
+    return [
+      { kind: 'field_name', text: term.relation_name },
+      { kind: 'operator', text: '=' },
+      { kind: 'literal', text: term.target_id },
+    ];
+  }
+
+  return [
+    { kind: 'field_name', text: term.relation_name },
+    { kind: 'operator', text: ':*' },
+  ];
+}
+
+/**
+ * @param {string} where_clause
+ * @returns {StoredQuerySegment[][]}
+ */
+function createFallbackPhrases(where_clause) {
+  const tokens = where_clause.match(/\S+/gu) ?? [];
+
+  if (tokens.length === 0) {
+    return [[{ kind: 'literal', text: where_clause }]];
+  }
+
+  return tokens.map((token) => [{ kind: 'literal', text: token }]);
+}
+
+/**
+ * @param {StoredQuerySegment[][]} phrases
+ * @param {number} term_column_width
+ * @returns {StoredQuerySegment[][]}
+ */
+function wrapPhrases(phrases, term_column_width) {
+  /** @type {StoredQuerySegment[][]} */
+  const lines = [];
+  /** @type {StoredQuerySegment[]} */
+  let current_line = [];
+  let current_width = 0;
+
+  for (const phrase of phrases) {
+    const phrase_width = measureSegments(phrase);
+
+    if (current_line.length === 0) {
+      current_line = [...phrase];
+      current_width = phrase_width;
+      continue;
+    }
+
+    if (current_width + 1 + phrase_width > term_column_width) {
+      lines.push(current_line);
+      current_line = [...phrase];
+      current_width = phrase_width;
+      continue;
+    }
+
+    current_line.push({ kind: 'plain', text: ' ' });
+    current_line.push(...phrase);
+    current_width += 1 + phrase_width;
+  }
+
+  if (current_line.length > 0) {
+    lines.push(current_line);
+  }
+
+  return lines;
+}
+
+/**
+ * @param {StoredQuerySegment[]} segments
+ * @returns {number}
+ */
+function measureSegments(segments) {
+  return segments.reduce(
+    (total_width, segment) => total_width + segment.text.length,
+    0,
+  );
+}

package/lib/list-queries.js

@@ -0,0 +1,18 @@
+/**
+ * @import { StoredQueryConfig } from './load-patram-config.types.ts';
+ */
+
+/**
+ * List stored queries in stable name order.
+ *
+ * @param {Record<string, StoredQueryConfig>} stored_queries
+ * @returns {{ name: string, where: string }[]}
+ */
+export function listQueries(stored_queries) {
+  return Object.entries(stored_queries)
+    .sort(([left_name], [right_name]) => left_name.localeCompare(right_name))
+    .map(([name, stored_query]) => ({
+      name,
+      where: stored_query.where,
+    }));
+}

package/lib/list-source-files.js

@@ -1,6 +1,21 @@
-import { glob } from 'node:fs/promises';
+import { globby } from 'globby';
 import process from 'node:process';
 
+/**
+ * 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.
  *
@@ -12,26 +27,46 @@ export async function listSourceFiles(
   include_patterns,
   project_directory = process.cwd(),
 ) {
-  /** @type {Set<string>} */
-  const source_file_paths = new Set();
+  const source_file_paths = await listMatchingFiles(
+    include_patterns,
+    project_directory,
+  );
+
+  return [...new Set(source_file_paths)].sort(comparePaths);
+}
 
-  for (const include_pattern of include_patterns) {
-    for await (const matched_path of glob(include_pattern, {
-      cwd: project_directory,
-    })) {
-      source_file_paths.add(normalizeRepoRelativePath(matched_path));
-    }
-  }
+/**
+ * List repo files available for broken-link validation.
+ *
+ * @param {string} [project_directory]
+ * @returns {Promise<string[]>}
+ */
+export async function listRepoFiles(project_directory = process.cwd()) {
+  const repo_file_paths = await listMatchingFiles(['**/*'], project_directory, {
+    dot: true,
+  });
 
-  return [...source_file_paths].sort(comparePaths);
+  return [...new Set(repo_file_paths)].sort(comparePaths);
 }
 
 /**
- * @param {string} source_path
- * @returns {string}
+ * @param {string[]} include_patterns
+ * @param {string} project_directory
+ * @param {{ dot?: boolean }} [options]
+ * @returns {Promise<string[]>}
  */
-function normalizeRepoRelativePath(source_path) {
-  return source_path.replaceAll('\\', '/');
+async function listMatchingFiles(
+  include_patterns,
+  project_directory,
+  options = {},
+) {
+  return globby(include_patterns, {
+    cwd: project_directory,
+    dot: options.dot ?? false,
+    expandDirectories: false,
+    gitignore: true,
+    onlyFiles: true,
+  });
 }
 
 /**

package/lib/load-patram-config.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines */
 /**
  * @import { LoadPatramConfigResult, PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
  */
@@ -8,6 +9,25 @@ import process from 'node:process';
 
 import { z } from 'zod';
 
+import { parsePatramConfig } from './patram-config.js';
+import { DEFAULT_INCLUDE_PATTERNS } from './source-file-defaults.js';
+
+/**
+ * Repo config loading.
+ *
+ * Reads `.patram.json`, applies defaults, and validates repo config and graph
+ * schema before command execution.
+ *
+ * Kind: config
+ * Status: active
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
+ * Decided by: ../docs/decisions/single-config-file.md
+ * Decided by: ../docs/decisions/optional-config-default-scan.md
+ * @patram
+ * @see {@link ./resolve-patram-graph-config.js}
+ * @see {@link ../docs/decisions/single-config-file.md}
+ */
+
 const CONFIG_FILE_NAME = '.patram.json';
 
 const stored_query_schema = z
@@ -20,8 +40,12 @@ const patram_repo_config_schema = z
   .object({
     include: z
       .array(z.string().min(1, 'Include globs must not be empty.'))
-      .min(1, 'Include must contain at least one glob.'),
-    queries: z.record(z.string().min(1), stored_query_schema),
+      .min(1, 'Include must contain at least one glob.')
+      .default(DEFAULT_INCLUDE_PATTERNS),
+    kinds: z.unknown().optional(),
+    mappings: z.unknown().optional(),
+    queries: z.record(z.string().min(1), stored_query_schema).default({}),
+    relations: z.unknown().optional(),
   })
   .strict();
 
@@ -36,7 +60,7 @@ export async function loadPatramConfig(project_directory = process.cwd()) {
   const config_source = await readConfigSource(config_file_path);
 
   if (config_source === null) {
-    return createLoadResult(null, [createMissingConfigDiagnostic()]);
+    return createLoadResult(createDefaultRepoConfig(), []);
   }
 
   const parse_result = parseConfigJson(config_source);
@@ -54,7 +78,13 @@ export async function loadPatramConfig(project_directory = process.cwd()) {
     );
   }
 
-  return createLoadResult(config_result.data, []);
+  const graph_schema_diagnostics = validateGraphSchema(config_result.data);
+
+  if (graph_schema_diagnostics.length > 0) {
+    return createLoadResult(null, graph_schema_diagnostics);
+  }
+
+  return createLoadResult(normalizeRepoConfig(config_result.data), []);
 }
 
 /**
@@ -108,20 +138,6 @@ function createLoadResult(config, diagnostics) {
   };
 }
 
-/**
- * @returns {PatramDiagnostic}
- */
-function createMissingConfigDiagnostic() {
-  return {
-    code: 'config.not_found',
-    column: 1,
-    level: 'error',
-    line: 1,
-    message: 'Config file ".patram.json" was not found.',
-    path: CONFIG_FILE_NAME,
-  };
-}
-
 /**
  * @param {string} config_source
  * @param {SyntaxError} error
@@ -168,6 +184,78 @@ function createValidationDiagnostic(issue) {
   };
 }
 
+/**
+ * @param {{ include: string[], queries: Record<string, { where: string }>, kinds?: unknown, mappings?: unknown, relations?: unknown }} repo_config
+ * @returns {PatramDiagnostic[]}
+ */
+function validateGraphSchema(repo_config) {
+  if (
+    repo_config.kinds === undefined &&
+    repo_config.mappings === undefined &&
+    repo_config.relations === undefined
+  ) {
+    return [];
+  }
+
+  try {
+    parsePatramConfig({
+      kinds: repo_config.kinds ?? {},
+      mappings: repo_config.mappings ?? {},
+      relations: repo_config.relations ?? {},
+    });
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return error.issues.map(createValidationDiagnostic);
+    }
+
+    throw error;
+  }
+
+  return [];
+}
+
+/**
+ * @returns {PatramRepoConfig}
+ */
+function createDefaultRepoConfig() {
+  return {
+    include: [...DEFAULT_INCLUDE_PATTERNS],
+    queries: {},
+  };
+}
+
+/**
+ * @param {{ include: string[], queries: Record<string, { where: string }>, kinds?: unknown, mappings?: unknown, relations?: unknown }} repo_config
+ * @returns {PatramRepoConfig}
+ */
+function normalizeRepoConfig(repo_config) {
+  /** @type {PatramRepoConfig} */
+  const normalized_config = {
+    include: [...repo_config.include],
+    queries: { ...repo_config.queries },
+  };
+
+  if (repo_config.kinds !== undefined && repo_config.kinds !== null) {
+    normalized_config.kinds = /** @type {PatramRepoConfig['kinds']} */ (
+      repo_config.kinds
+    );
+  }
+
+  if (repo_config.mappings !== undefined && repo_config.mappings !== null) {
+    normalized_config.mappings = /** @type {PatramRepoConfig['mappings']} */ (
+      repo_config.mappings
+    );
+  }
+
+  if (repo_config.relations !== undefined && repo_config.relations !== null) {
+    normalized_config.relations = /** @type {PatramRepoConfig['relations']} */ (
+      repo_config.relations
+    );
+  }
+
+  return normalized_config;
+}
+
 /**
  * @param {unknown} error
  * @returns {error is NodeJS.ErrnoException}