patram 0.10.0 → 0.11.0

package/lib/config/manage-stored-queries.js

@@ -0,0 +1,294 @@
+/**
+ * @import { CliParseError } from '../cli/arguments.types.ts';
+ * @import {
+ *   PatramDiagnostic,
+ *   PatramRepoConfig,
+ * } from './load-patram-config.types.ts';
+ */
+
+import { resolve } from 'node:path';
+
+import { loadPatramConfig } from './load-patram-config.js';
+import {
+  createStoredQueryDefinition,
+  createUpdatedStoredQueryDefinition,
+  ensureRawQueries,
+  loadRawConfig,
+  persistStoredQueryMutation,
+  rawQueryValueToRecord,
+} from './manage-stored-queries-helpers.js';
+import { CONFIG_FILE_NAME } from './schema.js';
+import { createUnknownStoredQueryError } from '../graph/query/resolve.js';
+
+/**
+ * @typedef {{
+ *   action: 'add',
+ *   description?: string,
+ *   name: string,
+ *   where: string,
+ * } | {
+ *   action: 'remove',
+ *   name: string,
+ * } | {
+ *   action: 'update',
+ *   description?: string,
+ *   name: string,
+ *   next_name?: string,
+ *   where?: string,
+ * }} StoredQueryMutation
+ */
+
+/**
+ * @typedef {{
+ *   action: 'added',
+ *   name: string,
+ * } | {
+ *   action: 'removed',
+ *   name: string,
+ * } | {
+ *   action: 'updated',
+ *   name: string,
+ *   previous_name?: string,
+ * }} StoredQueryMutationResult
+ */
+
+/**
+ * @param {string} project_directory
+ * @param {StoredQueryMutation} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+export async function manageStoredQueries(
+  project_directory,
+  stored_query_mutation,
+) {
+  const load_result = await loadPatramConfig(project_directory);
+
+  if (load_result.diagnostics.length > 0) {
+    return {
+      diagnostics: load_result.diagnostics,
+      success: false,
+    };
+  }
+
+  const repo_config = load_result.config;
+
+  if (!repo_config) {
+    throw new Error('Expected a valid Patram repo config.');
+  }
+
+  const config_file_path = resolve(project_directory, CONFIG_FILE_NAME);
+  const raw_config_result = await loadRawConfig(config_file_path);
+
+  if (!raw_config_result.success) {
+    return {
+      diagnostics: [raw_config_result.diagnostic],
+      success: false,
+    };
+  }
+
+  if (stored_query_mutation.action === 'add') {
+    return applyAddStoredQuery(
+      config_file_path,
+      raw_config_result.value,
+      repo_config,
+      stored_query_mutation,
+    );
+  }
+
+  if (stored_query_mutation.action === 'remove') {
+    return applyRemoveStoredQuery(
+      config_file_path,
+      raw_config_result.value,
+      repo_config,
+      stored_query_mutation,
+    );
+  }
+
+  return applyUpdateStoredQuery(
+    config_file_path,
+    raw_config_result.value,
+    repo_config,
+    stored_query_mutation,
+  );
+}
+
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {PatramRepoConfig} repo_config
+ * @param {{ description?: string, name: string, where: string }} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+async function applyAddStoredQuery(
+  config_file_path,
+  raw_config,
+  repo_config,
+  stored_query_mutation,
+) {
+  if (repo_config.queries[stored_query_mutation.name]) {
+    return {
+      error: {
+        code: 'message',
+        message: `Stored query already exists: ${stored_query_mutation.name}.`,
+      },
+      success: false,
+    };
+  }
+
+  const raw_queries = ensureRawQueries(raw_config);
+  raw_queries[stored_query_mutation.name] = createStoredQueryDefinition(
+    stored_query_mutation.where,
+    stored_query_mutation.description,
+  );
+
+  return persistStoredQueryMutation(config_file_path, raw_config, {
+    action: 'added',
+    name: stored_query_mutation.name,
+  });
+}
+
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {PatramRepoConfig} repo_config
+ * @param {{ name: string }} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+async function applyRemoveStoredQuery(
+  config_file_path,
+  raw_config,
+  repo_config,
+  stored_query_mutation,
+) {
+  if (!repo_config.queries[stored_query_mutation.name]) {
+    return {
+      error: createQueryMutationUnknownStoredQueryError(
+        stored_query_mutation.name,
+        Object.keys(repo_config.queries),
+        'remove',
+      ),
+      success: false,
+    };
+  }
+
+  const raw_queries = ensureRawQueries(raw_config);
+  delete raw_queries[stored_query_mutation.name];
+
+  return persistStoredQueryMutation(config_file_path, raw_config, {
+    action: 'removed',
+    name: stored_query_mutation.name,
+  });
+}
+
+/**
+ * @param {string} config_file_path
+ * @param {Record<string, unknown>} raw_config
+ * @param {PatramRepoConfig} repo_config
+ * @param {{ description?: string, name: string, next_name?: string, where?: string }} stored_query_mutation
+ * @returns {Promise<
+ *   | { success: true, value: StoredQueryMutationResult }
+ *   | { diagnostics: PatramDiagnostic[], success: false }
+ *   | { error: CliParseError, success: false }
+ * >}
+ */
+async function applyUpdateStoredQuery(
+  config_file_path,
+  raw_config,
+  repo_config,
+  stored_query_mutation,
+) {
+  const existing_query = repo_config.queries[stored_query_mutation.name];
+
+  if (!existing_query) {
+    return {
+      error: createQueryMutationUnknownStoredQueryError(
+        stored_query_mutation.name,
+        Object.keys(repo_config.queries),
+        'update',
+      ),
+      success: false,
+    };
+  }
+
+  const next_name =
+    stored_query_mutation.next_name ?? stored_query_mutation.name;
+
+  if (
+    next_name !== stored_query_mutation.name &&
+    repo_config.queries[next_name]
+  ) {
+    return {
+      error: {
+        code: 'message',
+        message: `Stored query already exists: ${next_name}.`,
+      },
+      success: false,
+    };
+  }
+
+  const raw_queries = ensureRawQueries(raw_config);
+  const raw_query_value = rawQueryValueToRecord(
+    raw_queries[stored_query_mutation.name],
+  );
+  const next_query = createUpdatedStoredQueryDefinition(
+    raw_query_value,
+    existing_query,
+    stored_query_mutation,
+  );
+
+  if (next_name !== stored_query_mutation.name) {
+    delete raw_queries[stored_query_mutation.name];
+  }
+
+  raw_queries[next_name] = next_query;
+
+  return persistStoredQueryMutation(config_file_path, raw_config, {
+    action: 'updated',
+    name: next_name,
+    previous_name:
+      next_name === stored_query_mutation.name
+        ? undefined
+        : stored_query_mutation.name,
+  });
+}
+
+/**
+ * @param {string} stored_query_name
+ * @param {string[]} stored_query_names
+ * @param {'remove' | 'update'} subcommand_name
+ * @returns {CliParseError}
+ */
+function createQueryMutationUnknownStoredQueryError(
+  stored_query_name,
+  stored_query_names,
+  subcommand_name,
+) {
+  const parse_error = createUnknownStoredQueryError(
+    stored_query_name,
+    stored_query_names,
+  );
+
+  if (
+    parse_error.code !== 'unknown_stored_query' ||
+    parse_error.suggestion === undefined
+  ) {
+    return parse_error;
+  }
+
+  return {
+    ...parse_error,
+    next_path: `patram queries ${subcommand_name} ${parse_error.suggestion}`,
+  };
+}

package/lib/config/validate-patram-config-value.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param {unknown} config_value
+ * @returns {{ config: PatramRepoConfig, success: true } | { diagnostics: PatramDiagnostic[], success: false }}
+ */
+export function validatePatramConfigValue(config_value: unknown): {
+    config: PatramRepoConfig;
+    success: true;
+} | {
+    diagnostics: PatramDiagnostic[];
+    success: false;
+};
+import type { PatramRepoConfig } from './load-patram-config.types.d.ts';
+import type { PatramDiagnostic } from './load-patram-config.types.d.ts';

package/lib/config/validate-patram-config-value.js

@@ -0,0 +1,119 @@
+/**
+ * @import {
+ *   PatramDiagnostic,
+ *   PatramRepoConfig,
+ * } from './load-patram-config.types.ts';
+ */
+
+import { patram_repo_config_schema } from './schema.js';
+import { normalizeRepoConfig } from './defaults.js';
+import {
+  validateDerivedSummaries,
+  validateFieldSchemaConfig,
+  validateGraphSchema,
+  validateLegacyConfigShape,
+  validateStoredQueries,
+} from './validation.js';
+
+/**
+ * @param {unknown} config_value
+ * @returns {{ config: PatramRepoConfig, success: true } | { diagnostics: PatramDiagnostic[], success: false }}
+ */
+export function validatePatramConfigValue(config_value) {
+  const legacy_config_diagnostics = validateLegacyConfigShape(config_value);
+
+  if (legacy_config_diagnostics.length > 0) {
+    return {
+      diagnostics: legacy_config_diagnostics,
+      success: false,
+    };
+  }
+
+  const config_result = patram_repo_config_schema.safeParse(config_value);
+
+  if (!config_result.success) {
+    return {
+      diagnostics: config_result.error.issues.map(createValidationDiagnostic),
+      success: false,
+    };
+  }
+
+  const graph_schema_diagnostics = validateGraphSchema(config_result.data);
+
+  if (graph_schema_diagnostics.length > 0) {
+    return {
+      diagnostics: graph_schema_diagnostics,
+      success: false,
+    };
+  }
+
+  const normalized_config = normalizeRepoConfig(config_result.data);
+  const field_schema_diagnostics = validateFieldSchemaConfig(normalized_config);
+
+  if (field_schema_diagnostics.length > 0) {
+    return {
+      diagnostics: field_schema_diagnostics,
+      success: false,
+    };
+  }
+
+  const stored_query_diagnostics = validateStoredQueries(normalized_config);
+
+  if (stored_query_diagnostics.length > 0) {
+    return {
+      diagnostics: stored_query_diagnostics,
+      success: false,
+    };
+  }
+
+  const derived_summary_diagnostics =
+    validateDerivedSummaries(normalized_config);
+
+  if (derived_summary_diagnostics.length > 0) {
+    return {
+      diagnostics: derived_summary_diagnostics,
+      success: false,
+    };
+  }
+
+  return {
+    config: normalized_config,
+    success: true,
+  };
+}
+
+/**
+ * @param {import('zod').core.$ZodIssue} issue
+ * @returns {PatramDiagnostic}
+ */
+function createValidationDiagnostic(issue) {
+  const issue_path = formatIssuePath(issue.path);
+
+  if (issue_path) {
+    return {
+      code: 'config.invalid',
+      column: 1,
+      level: 'error',
+      line: 1,
+      message: `Invalid config at "${issue_path}": ${issue.message}`,
+      path: '.patram.json',
+    };
+  }
+
+  return {
+    code: 'config.invalid',
+    column: 1,
+    level: 'error',
+    line: 1,
+    message: `Invalid config: ${issue.message}`,
+    path: '.patram.json',
+  };
+}
+
+/**
+ * @param {(string | number | symbol | undefined)[]} issue_path
+ * @returns {string}
+ */
+function formatIssuePath(issue_path) {
+  return issue_path.map(String).join('.');
+}

package/lib/graph/query/resolve.d.ts

@@ -18,6 +18,12 @@ export function resolveWhereClause(repo_config: PatramRepoConfig, command_argume
     error: CliParseError;
     success: false;
 };
+/**
+ * @param {string} stored_query_name
+ * @param {string[]} stored_query_names
+ * @returns {CliParseError}
+ */
+export function createUnknownStoredQueryError(stored_query_name: string, stored_query_names: string[]): CliParseError;
 export type QuerySource = {
     kind: "ad_hoc";
 } | {

package/lib/graph/query/resolve.js

@@ -82,7 +82,10 @@ export function resolveWhereClause(repo_config, command_arguments) {
  * @param {string[]} stored_query_names
  * @returns {CliParseError}
  */
-function createUnknownStoredQueryError(stored_query_name, stored_query_names) {
+export function createUnknownStoredQueryError(
+  stored_query_name,
+  stored_query_names,
+) {
   const suggestion = findCloseMatch(stored_query_name, stored_query_names);
 
   if (!suggestion) {

package/lib/output/resolve-check-target.js

@@ -21,7 +21,7 @@ const CONFIG_FILE_NAME = '.patram.json';
  * @param {string | undefined} target_argument
  * @returns {Promise<ResolvedCheckTarget>}
  */
-export async function resolveCheckTarget(target_argument) {
+async function resolveCheckTarget(target_argument) {
   if (target_argument === undefined) {
     return {
       project_directory: process.cwd(),
@@ -35,23 +35,19 @@ export async function resolveCheckTarget(target_argument) {
     ? 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,
@@ -65,7 +61,36 @@ export async function resolveCheckTarget(target_argument) {
     target_path,
   };
 }
+/**
+ * @param {string[]} target_arguments
+ * @returns {Promise<ResolvedCheckTarget[]>}
+ */
+export async function resolveCheckTargets(target_arguments) {
+  if (target_arguments.length === 0) {
+    return [await resolveCheckTarget(undefined)];
+  }
 
+  return Promise.all(
+    target_arguments.map((target_argument) =>
+      resolveCheckTarget(target_argument),
+    ),
+  );
+}
+/** @param {ResolvedCheckTarget[]} resolved_targets
+ * @returns {string | null}
+ */
+export function resolveCheckTargetProjectDirectory(resolved_targets) {
+  const project_directory = resolved_targets[0]?.project_directory;
+  if (!project_directory) {
+    return null;
+  }
+  for (const resolved_target of resolved_targets) {
+    if (resolved_target.project_directory !== project_directory) {
+      return null;
+    }
+  }
+  return project_directory;
+}
 /**
  * Select the source files covered by one resolved `check` target.
  *
@@ -73,10 +98,7 @@ export async function resolveCheckTarget(target_argument) {
  * @param {ResolvedCheckTarget} resolved_target
  * @returns {string[]}
  */
-export function selectCheckTargetSourceFiles(
-  source_file_paths,
-  resolved_target,
-) {
+function selectCheckTargetSourceFiles(source_file_paths, resolved_target) {
   if (resolved_target.target_kind === 'project') {
     return source_file_paths;
   }
@@ -91,7 +113,22 @@ export function selectCheckTargetSourceFiles(
     isPathInsideDirectory(source_file_path, resolved_target.target_path),
   );
 }
-
+/**
+ * @param {string[]} source_file_paths
+ * @param {ResolvedCheckTarget[]} resolved_targets
+ * @returns {string[]}
+ */
+export function selectCheckTargetsSourceFiles(
+  source_file_paths,
+  resolved_targets,
+) {
+  return selectCheckTargetValues(
+    source_file_paths,
+    resolved_targets,
+    selectCheckTargetSourceFiles,
+    (source_file_path) => source_file_path,
+  );
+}
 /**
  * Filter diagnostics to one resolved `check` target.
  *
@@ -99,7 +136,7 @@ export function selectCheckTargetSourceFiles(
  * @param {ResolvedCheckTarget} resolved_target
  * @returns {PatramDiagnostic[]}
  */
-export function selectCheckTargetDiagnostics(diagnostics, resolved_target) {
+function selectCheckTargetDiagnostics(diagnostics, resolved_target) {
   if (resolved_target.target_kind === 'project') {
     return diagnostics;
   }
@@ -115,6 +152,20 @@ export function selectCheckTargetDiagnostics(diagnostics, resolved_target) {
   );
 }
 
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {ResolvedCheckTarget[]} resolved_targets
+ * @returns {PatramDiagnostic[]}
+ */
+export function selectCheckTargetsDiagnostics(diagnostics, resolved_targets) {
+  return selectCheckTargetValues(
+    diagnostics,
+    resolved_targets,
+    selectCheckTargetDiagnostics,
+    createDiagnosticKey,
+  );
+}
+
 /**
  * @param {string} start_directory
  * @returns {Promise<string>}
@@ -155,6 +206,49 @@ async function hasConfigFile(directory_path) {
   return true;
 }
 
+/**
+ * @template ValueType
+ * @param {ValueType[]} values
+ * @param {ResolvedCheckTarget[]} resolved_targets
+ * @param {(values: ValueType[], resolved_target: ResolvedCheckTarget) => ValueType[]} select_values
+ * @param {(value: ValueType) => string} get_value_key
+ * @returns {ValueType[]}
+ */
+function selectCheckTargetValues(
+  values,
+  resolved_targets,
+  select_values,
+  get_value_key,
+) {
+  if (
+    resolved_targets.some(
+      (resolved_target) => resolved_target.target_kind === 'project',
+    )
+  ) {
+    return values;
+  }
+
+  /** @type {Set<string>} */
+  const selected_keys = new Set();
+  /** @type {ValueType[]} */
+  const selected_values = [];
+
+  for (const resolved_target of resolved_targets) {
+    for (const value of select_values(values, resolved_target)) {
+      const value_key = get_value_key(value);
+
+      if (selected_keys.has(value_key)) {
+        continue;
+      }
+
+      selected_keys.add(value_key);
+      selected_values.push(value);
+    }
+  }
+
+  return selected_values;
+}
+
 /**
  * @param {string} source_path
  * @param {string} directory_path
@@ -175,6 +269,21 @@ function normalizeRepoRelativePath(source_path) {
   return source_path.replaceAll('\\', '/');
 }
 
+/**
+ * @param {PatramDiagnostic} diagnostic
+ * @returns {string}
+ */
+function createDiagnosticKey(diagnostic) {
+  return [
+    diagnostic.path,
+    diagnostic.line,
+    diagnostic.column,
+    diagnostic.level,
+    diagnostic.code,
+    diagnostic.message,
+  ].join(':');
+}
+
 /**
  * @param {unknown} error
  * @returns {error is NodeJS.ErrnoException}

package/lib/patram.d.ts

@@ -48,6 +48,8 @@ export type PatramParsedTerm =
   import('./graph/parse-where-clause.types.d.ts').ParsedTerm;
 export type PatramParsedExpression =
   import('./graph/parse-where-clause.types.d.ts').ParsedExpression;
+export type PatramParseResult =
+  import('./graph/parse-where-clause.types.d.ts').ParseWhereClauseResult;
 export type PatramParseWhereClauseResult =
   import('./graph/parse-where-clause.types.d.ts').ParseWhereClauseResult;
 export type PatramQuerySource =
@@ -59,6 +61,12 @@ export type PatramQuerySource =
       name: string;
     };
 
+export interface PatramQueryGraphOptions {
+  bindings?: Record<string, string>;
+  limit?: number;
+  offset?: number;
+}
+
 export interface PatramProjectGraphResult {
   claims: import('./parse/parse-claims.types.d.ts').PatramClaim[];
   config: import('./config/load-patram-config.types.d.ts').PatramRepoConfig;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patram",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "main": "./lib/patram.js",
   "types": "./lib/patram.d.ts",
@@ -67,6 +67,7 @@
     "ansis": "^4.2.0",
     "beautiful-mermaid": "^1.1.3",
     "globby": "^16.1.1",
+    "jsonc-parser": "^3.3.1",
     "md4x": "^0.0.25",
     "shiki": "^4.0.2",
     "string-width": "^8.2.0",