patram 0.4.0 → 0.6.0

package/lib/check-directive-value.js

@@ -4,7 +4,10 @@
  * @import { MappingDefinition } from './patram-config.types.ts';
  */
 
-import { resolveTargetReference } from './build-graph-identity.js';
+import {
+  createPathClassDiagnostics,
+  createPathExistenceDiagnostics,
+} from './check-directive-path-target.js';
 import { createOriginDiagnostic } from './directive-diagnostics.js';
 import {
   formatQuotedList,
@@ -40,45 +43,31 @@ export function checkDirectiveValue(
     directive_name,
     mapping_definition,
   );
-
   if (!validation_field_name || typeof claim.value !== 'string') {
     return [];
   }
-
+  const directive_value = claim.value;
   if (validation_field_name === '$class') {
-    return checkClassValue(claim, directive_name, repo_config);
-  }
-
-  if (isStructuralDirectiveField(validation_field_name)) {
-    return [];
+    return checkClassValue(claim, directive_name, directive_value, repo_config);
   }
-
   const type_definition = repo_config.fields?.[validation_field_name];
-
-  if (!type_definition) {
-    return [];
-  }
-
-  if (type_definition.type === 'enum') {
-    return checkEnumValue(claim, directive_name, type_definition.values);
-  }
-
-  const type_diagnostic = createInvalidTypeDiagnostic(
-    claim,
-    directive_name,
-    type_definition,
-    claim.value,
-  );
-
-  if (type_diagnostic) {
-    return [type_diagnostic];
+  if (isStructuralDirectiveField(validation_field_name) || !type_definition) {
+    return collectUntypedPathDiagnostics(
+      claim,
+      directive_name,
+      mapping_definition,
+      document_entity_keys,
+      document_node_references,
+      document_paths,
+    );
   }
-
-  return createPathClassDiagnostics(
+  return checkTypedDirectiveValue(
     claim,
     directive_name,
+    directive_value,
     mappings,
     repo_config,
+    mapping_definition,
     type_definition,
     document_entity_keys,
     document_node_references,
@@ -89,14 +78,12 @@ export function checkDirectiveValue(
 /**
  * @param {PatramClaim} claim
  * @param {string} directive_name
+ * @param {string} class_name
  * @param {PatramRepoConfig} repo_config
  * @returns {PatramDiagnostic[]}
  */
-function checkClassValue(claim, directive_name, repo_config) {
-  if (
-    typeof claim.value !== 'string' ||
-    repo_config.classes?.[claim.value] !== undefined
-  ) {
+function checkClassValue(claim, directive_name, class_name, repo_config) {
+  if (repo_config.classes?.[class_name] !== undefined) {
     return [];
   }
 
@@ -112,44 +99,85 @@ function checkClassValue(claim, directive_name, repo_config) {
 /**
  * @param {PatramClaim} claim
  * @param {string} directive_name
- * @param {string[]} allowed_values
+ * @param {string} directive_value
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramRepoConfig} repo_config
+ * @param {MappingDefinition | null} mapping_definition
+ * @param {DirectiveTypeConfig} type_definition
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Set<string>} document_paths
  * @returns {PatramDiagnostic[]}
  */
-function checkEnumValue(claim, directive_name, allowed_values) {
-  if (typeof claim.value !== 'string' || allowed_values.includes(claim.value)) {
-    return [];
+function checkTypedDirectiveValue(
+  claim,
+  directive_name,
+  directive_value,
+  mappings,
+  repo_config,
+  mapping_definition,
+  type_definition,
+  document_entity_keys,
+  document_node_references,
+  document_paths,
+) {
+  if (type_definition.type === 'enum') {
+    return checkEnumValue(
+      claim,
+      directive_name,
+      directive_value,
+      type_definition.values,
+    );
   }
 
-  return [
-    createOriginDiagnostic(
-      claim,
-      'directive.invalid_enum',
-      `Directive "${directive_name}" must be one of ${formatQuotedList(allowed_values)}.`,
-    ),
-  ];
+  if (!isDirectiveValueValid(type_definition, directive_value)) {
+    return [
+      createOriginDiagnostic(
+        claim,
+        'directive.invalid_type',
+        getInvalidTypeMessage(directive_name, type_definition.type),
+      ),
+    ];
+  }
+
+  return collectPathDiagnostics(
+    claim,
+    directive_name,
+    mappings,
+    repo_config,
+    mapping_definition,
+    type_definition,
+    document_entity_keys,
+    document_node_references,
+    document_paths,
+  );
 }
 
 /**
  * @param {PatramClaim} claim
  * @param {string} directive_name
- * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }>} type_definition
- * @param {string} directive_value
- * @returns {PatramDiagnostic | null}
+ * @param {MappingDefinition | null} mapping_definition
+ * @param {Map<string, string>} document_entity_keys
+ * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Set<string>} document_paths
+ * @returns {PatramDiagnostic[]}
  */
-function createInvalidTypeDiagnostic(
+function collectUntypedPathDiagnostics(
   claim,
   directive_name,
-  type_definition,
-  directive_value,
+  mapping_definition,
+  document_entity_keys,
+  document_node_references,
+  document_paths,
 ) {
-  if (isDirectiveValueValid(type_definition, directive_value)) {
-    return null;
-  }
-
-  return createOriginDiagnostic(
+  return createPathExistenceDiagnostics(
     claim,
-    'directive.invalid_type',
-    getInvalidTypeMessage(directive_name, type_definition.type),
+    directive_name,
+    mapping_definition,
+    undefined,
+    document_entity_keys,
+    document_node_references,
+    document_paths,
   );
 }
 
@@ -158,90 +186,70 @@ function createInvalidTypeDiagnostic(
  * @param {string} directive_name
  * @param {Record<string, MappingDefinition>} mappings
  * @param {PatramRepoConfig} repo_config
+ * @param {MappingDefinition | null} mapping_definition
  * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }>} type_definition
  * @param {Map<string, string>} document_entity_keys
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
  * @param {Set<string>} document_paths
  * @returns {PatramDiagnostic[]}
  */
-function createPathClassDiagnostics(
+function collectPathDiagnostics(
   claim,
   directive_name,
   mappings,
   repo_config,
+  mapping_definition,
   type_definition,
   document_entity_keys,
   document_node_references,
   document_paths,
 ) {
-  if (
-    type_definition.type !== 'path' ||
-    type_definition.path_class === undefined ||
-    isDirectivePathInClass(
-      mappings,
+  return createPathClassDiagnostics(
+    claim,
+    directive_name,
+    mappings,
+    repo_config,
+    type_definition,
+    document_entity_keys,
+    document_node_references,
+    document_paths,
+  ).concat(
+    createPathExistenceDiagnostics(
       claim,
-      type_definition.path_class,
+      directive_name,
+      mapping_definition,
+      type_definition,
       document_entity_keys,
       document_node_references,
       document_paths,
-      repo_config,
-    )
-  ) {
-    return [];
-  }
-
-  return [
-    createOriginDiagnostic(
-      claim,
-      'directive.invalid_path_class',
-      `Directive "${directive_name}" must point to path class "${type_definition.path_class}".`,
     ),
-  ];
+  );
 }
 
 /**
- * @param {Record<string, MappingDefinition>} mappings
  * @param {PatramClaim} claim
- * @param {string} path_class_name
- * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
- * @param {Set<string>} document_paths
- * @param {PatramRepoConfig} repo_config
- * @returns {boolean}
+ * @param {string} directive_name
+ * @param {string} directive_value
+ * @param {string[]} allowed_values
+ * @returns {PatramDiagnostic[]}
  */
-function isDirectivePathInClass(
-  mappings,
+function checkEnumValue(
   claim,
-  path_class_name,
-  document_entity_keys,
-  document_node_references,
-  document_paths,
-  repo_config,
+  directive_name,
+  directive_value,
+  allowed_values,
 ) {
-  const path_class_definition = repo_config.path_classes?.[path_class_name];
-
-  if (!path_class_definition) {
-    return true;
-  }
-
-  const mapping_definition = resolveDirectiveMapping(mappings, claim);
-  const target_kind = mapping_definition?.emit?.target_class ?? 'document';
-  const resolved_target = resolveTargetReference(
-    target_kind,
-    'path',
-    claim,
-    document_entity_keys,
-    document_node_references,
-    document_paths,
-  );
-
-  if (!resolved_target.path) {
-    return false;
+  if (allowed_values.includes(directive_value)) {
+    return [];
   }
 
-  return path_class_definition.prefixes.some((prefix) =>
-    resolved_target.path?.startsWith(prefix),
-  );
+  return [
+    createOriginDiagnostic(
+      claim,
+      'directive.invalid_enum',
+      `Directive "${directive_name}" must be one of ${formatQuotedList(allowed_values)}.`,
+    ),
+  ];
 }
 
 /**
@@ -263,11 +271,7 @@ function resolveDirectiveMapping(mappings, claim) {
  * @returns {string}
  */
 function getDirectiveValidationFieldName(directive_name, mapping_definition) {
-  if (mapping_definition?.node?.field) {
-    return mapping_definition.node.field;
-  }
-
-  return directive_name;
+  return mapping_definition?.node?.field ?? directive_name;
 }
 
 /**
@@ -282,10 +286,3 @@ function isStructuralDirectiveField(field_name) {
     field_name === 'title'
   );
 }
-
-/**
- * @param {PatramClaim} claim
- * @param {string} code
- * @param {string} message
- * @returns {PatramDiagnostic}
- */

package/lib/directive-validation-test-helpers.js

@@ -0,0 +1,87 @@
+/**
+ * @import { MappingDefinition } from './patram-config.types.ts';
+ */
+
+/**
+ * @returns {Record<string, { prefixes: string[] }>}
+ */
+export function createDirectivePathClasses() {
+  return {
+    decision_docs: {
+      prefixes: ['docs/decisions/'],
+    },
+    plan_docs: {
+      prefixes: ['docs/plans/'],
+    },
+    task_docs: {
+      prefixes: ['docs/tasks/'],
+    },
+  };
+}
+
+/**
+ * @returns {Record<string, { from: string[], to: string[] }>}
+ */
+export function createDirectiveRelations() {
+  return {
+    decided_by: {
+      from: ['document'],
+      to: ['document'],
+    },
+    tracked_in: {
+      from: ['document'],
+      to: ['document'],
+    },
+  };
+}
+
+/**
+ * @returns {Record<string, MappingDefinition>}
+ */
+export function createMarkdownDirectiveMappings() {
+  return {
+    'markdown.directive.decided_by': createRelationMapping('decided_by'),
+    'markdown.directive.kind': createNodeMapping('$class'),
+    'markdown.directive.status': createNodeMapping('status'),
+    'markdown.directive.tracked_in': createRelationMapping('tracked_in'),
+  };
+}
+
+/**
+ * @returns {Record<string, MappingDefinition>}
+ */
+export function createJsdocDirectiveMappings() {
+  return {
+    'jsdoc.directive.decided_by': createRelationMapping('decided_by'),
+    'jsdoc.directive.kind': createNodeMapping('$class'),
+    'jsdoc.directive.status': createNodeMapping('status'),
+    'jsdoc.directive.tracked_in': createRelationMapping('tracked_in'),
+  };
+}
+
+/**
+ * @param {string} field_name
+ * @returns {MappingDefinition}
+ */
+function createNodeMapping(field_name) {
+  return {
+    node: {
+      class: 'document',
+      field: field_name,
+    },
+  };
+}
+
+/**
+ * @param {string} relation_name
+ * @returns {MappingDefinition}
+ */
+function createRelationMapping(relation_name) {
+  return {
+    emit: {
+      relation: relation_name,
+      target: 'path',
+      target_class: 'document',
+    },
+  };
+}