patram 0.0.2 → 0.2.0

package/lib/layout-stored-queries.js

@@ -0,0 +1,361 @@
+/* eslint-disable max-lines */
+/**
+ * @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:
+ *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }
+ *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }
+ *     | { kind: 'relation', relation_name: string }
+ *     | { kind: 'relation_target', relation_name: string, target_id: string }
+ *     | {
+ *         aggregate_name: 'any' | 'count' | 'none',
+ *         clauses: unknown[],
+ *         comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
+ *         kind: 'aggregate',
+ *         traversal: { direction: 'in' | 'out', relation_name: string },
+ *         value?: number,
+ *       },
+ * }} 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 {
+ *   | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }
+ *   | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }
+ *   | { kind: 'relation', relation_name: string }
+ *   | { kind: 'relation_target', relation_name: string, target_id: string }
+ *   | {
+ *       aggregate_name: 'any' | 'count' | 'none',
+ *       clauses: { is_negated: boolean, term: unknown }[],
+ *       comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
+ *       kind: 'aggregate',
+ *       traversal: { direction: 'in' | 'out', relation_name: string },
+ *       value?: number,
+ *     }
+ * } term
+ * @returns {StoredQuerySegment[]}
+ */
+function createTermSegments(term) {
+  if (term.kind === 'aggregate') {
+    return createAggregateSegments(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 === 'field_set') {
+    return createFieldSetSegments(term);
+  }
+
+  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 {{ field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }} term
+ * @returns {StoredQuerySegment[]}
+ */
+function createFieldSetSegments(term) {
+  return [
+    { kind: 'field_name', text: term.field_name },
+    { kind: 'plain', text: ' ' },
+    { kind: 'operator', text: term.operator },
+    { kind: 'plain', text: ' ' },
+    { kind: 'operator', text: '[' },
+    ...createListSegments(term.values),
+    { kind: 'operator', text: ']' },
+  ];
+}
+
+/**
+ * @param {{
+ *   aggregate_name: 'any' | 'count' | 'none',
+ *   clauses: { is_negated: boolean, term: unknown }[],
+ *   comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
+ *   kind: 'aggregate',
+ *   traversal: { direction: 'in' | 'out', relation_name: string },
+ *   value?: number,
+ * }} term
+ * @returns {StoredQuerySegment[]}
+ */
+function createAggregateSegments(term) {
+  /** @type {StoredQuerySegment[]} */
+  const segments = [
+    { kind: 'field_name', text: term.aggregate_name },
+    { kind: 'operator', text: '(' },
+    ...createTraversalSegments(term.traversal),
+    { kind: 'operator', text: ', ' },
+    ...createNestedClauseSegments(term.clauses),
+    { kind: 'operator', text: ')' },
+  ];
+
+  if (term.aggregate_name === 'count') {
+    segments.push({ kind: 'plain', text: ' ' });
+    segments.push({ kind: 'operator', text: term.comparison ?? '=' });
+    segments.push({ kind: 'plain', text: ' ' });
+    segments.push({ kind: 'literal', text: String(term.value ?? 0) });
+  }
+
+  return segments;
+}
+
+/**
+ * @param {{ direction: 'in' | 'out', relation_name: string }} traversal
+ * @returns {StoredQuerySegment[]}
+ */
+function createTraversalSegments(traversal) {
+  return [
+    { kind: 'field_name', text: traversal.direction },
+    { kind: 'operator', text: ':' },
+    { kind: 'field_name', text: traversal.relation_name },
+  ];
+}
+
+/**
+ * @param {{ is_negated: boolean, term: unknown }[]} clauses
+ * @returns {StoredQuerySegment[]}
+ */
+function createNestedClauseSegments(clauses) {
+  return clauses.flatMap((clause, clause_index) => {
+    const clause_phrase = createClausePhrase(
+      /** @type {{
+       *   is_negated: boolean,
+       *   term:
+       *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field', operator: '=' | '^=' | '~', value: string }
+       *     | { field_name: 'id' | 'kind' | 'path' | 'status' | 'title', kind: 'field_set', operator: 'in' | 'not in', values: string[] }
+       *     | { kind: 'relation', relation_name: string }
+       *     | { kind: 'relation_target', relation_name: string, target_id: string }
+       *     | {
+       *         aggregate_name: 'any' | 'count' | 'none',
+       *         clauses: { is_negated: boolean, term: unknown }[],
+       *         comparison?: '!=' | '<' | '<=' | '=' | '>' | '>=',
+       *         kind: 'aggregate',
+       *         traversal: { direction: 'in' | 'out', relation_name: string },
+       *         value?: number,
+       *       },
+       * }} */ (clause),
+      clause_index > 0,
+    );
+
+    if (clause_index === 0) {
+      return clause_phrase;
+    }
+
+    return [{ kind: 'plain', text: ' ' }, ...clause_phrase];
+  });
+}
+
+/**
+ * @param {string[]} values
+ * @returns {StoredQuerySegment[]}
+ */
+function createListSegments(values) {
+  return values.flatMap((value, value_index) => {
+    if (value_index === 0) {
+      return [{ kind: 'literal', text: value }];
+    }
+
+    return [
+      { kind: 'operator', text: ', ' },
+      { kind: 'literal', text: value },
+    ];
+  });
+}
+
+/**
+ * @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,
+  });
 }
 
 /**