patram 0.5.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',
+    },
+  };
+}

package/lib/load-patram-config.js

@@ -40,6 +40,14 @@ import { DEFAULT_INCLUDE_PATTERNS } from './source-file-defaults.js';
 
 const CONFIG_FILE_NAME = '.patram.json';
 const RESERVED_STRUCTURAL_FIELD_NAMES = new Set(['$class', '$id', '$path']);
+const MARKDOWN_STYLE_NAMES = [
+  'front_matter',
+  'visible_line',
+  'list_item',
+  'hidden_tag',
+];
+const MARKDOWN_STYLE_NAME_SET = new Set(MARKDOWN_STYLE_NAMES);
+const MIXED_STYLE_VALUES = new Set(['ignore', 'error']);
 
 /**
  * @typedef {object} PatramDiagnostic
@@ -224,6 +232,7 @@ const metadata_field_schema = z.discriminatedUnion('type', [
  */
 const class_field_rule_schema = z
   .object({
+    markdown_styles: z.array(z.string().min(1)).optional(),
     presence: z.enum(['required', 'optional', 'forbidden']),
   })
   .strict();
@@ -235,6 +244,8 @@ const class_schema_schema = z
   .object({
     document_path_class: z.string().min(1).optional(),
     fields: z.record(z.string().min(1), class_field_rule_schema).default({}),
+    markdown_styles: z.array(z.string().min(1)).optional(),
+    mixed_styles: z.string().min(1).optional(),
     unknown_fields: z.enum(['ignore', 'error']).optional(),
   })
   .strict();
@@ -926,17 +937,32 @@ function collectClassSchemaConfigDiagnostics(
       continue;
     }
 
+    collectMarkdownStylesDiagnostic(
+      diagnostics,
+      `classes.${class_name}.schema.markdown_styles`,
+      schema_definition.markdown_styles,
+    );
+    collectMixedStylesDiagnostic(
+      diagnostics,
+      `classes.${class_name}.schema.mixed_styles`,
+      schema_definition.mixed_styles,
+    );
+
     for (const field_name of Object.keys(schema_definition.fields)) {
       if (fields[field_name]) {
-        continue;
+        collectMarkdownStylesDiagnostic(
+          diagnostics,
+          `classes.${class_name}.schema.fields.${field_name}.markdown_styles`,
+          schema_definition.fields[field_name].markdown_styles,
+        );
+      } else {
+        diagnostics.push(
+          createConfigDiagnostic(
+            `classes.${class_name}.schema.fields.${field_name}`,
+            `Unknown field "${field_name}".`,
+          ),
+        );
       }
-
-      diagnostics.push(
-        createConfigDiagnostic(
-          `classes.${class_name}.schema.fields.${field_name}`,
-          `Unknown field "${field_name}".`,
-        ),
-      );
     }
   }
 
@@ -963,6 +989,67 @@ function collectClassSchemaConfigDiagnostics(
   }
 }
 
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} diagnostic_path
+ * @param {string[] | undefined} markdown_styles
+ */
+function collectMarkdownStylesDiagnostic(
+  diagnostics,
+  diagnostic_path,
+  markdown_styles,
+) {
+  if (markdown_styles === undefined) {
+    return;
+  }
+
+  if (markdown_styles.length === 0) {
+    diagnostics.push(
+      createConfigDiagnostic(
+        diagnostic_path,
+        'Markdown styles must contain at least one style.',
+      ),
+    );
+
+    return;
+  }
+
+  for (const markdown_style of markdown_styles) {
+    if (MARKDOWN_STYLE_NAME_SET.has(markdown_style)) {
+      continue;
+    }
+
+    diagnostics.push(
+      createConfigDiagnostic(
+        diagnostic_path,
+        `Unknown markdown style "${markdown_style}".`,
+      ),
+    );
+  }
+}
+
+/**
+ * @param {PatramDiagnostic[]} diagnostics
+ * @param {string} diagnostic_path
+ * @param {string | undefined} mixed_styles
+ */
+function collectMixedStylesDiagnostic(
+  diagnostics,
+  diagnostic_path,
+  mixed_styles,
+) {
+  if (mixed_styles === undefined || MIXED_STYLE_VALUES.has(mixed_styles)) {
+    return;
+  }
+
+  diagnostics.push(
+    createConfigDiagnostic(
+      diagnostic_path,
+      'Mixed styles must be "ignore" or "error".',
+    ),
+  );
+}
+
 /**
  * @param {PatramRepoConfig['classes']} classes
  * @returns {Record<string, ClassDefinition>}

package/lib/load-project-graph.js

@@ -10,7 +10,7 @@ import { resolve } from 'node:path';
 import { buildGraph } from './build-graph.js';
 import { listSourceFiles } from './list-source-files.js';
 import { loadPatramConfig } from './load-patram-config.js';
-import { parseSourceFile } from './parse-claims.js';
+import { createParseOptions, parseSourceFile } from './parse-claims.js';
 import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
 
 /**
@@ -68,6 +68,7 @@ export async function loadProjectGraph(project_directory) {
     project_directory,
   );
   const collect_result = await collectClaims(
+    repo_config,
     source_file_paths,
     project_directory,
   );
@@ -96,25 +97,34 @@ export async function loadProjectGraph(project_directory) {
 }
 
 /**
+ * @param {PatramRepoConfig} repo_config
  * @param {string[]} source_file_paths
  * @param {string} project_directory
  * @returns {Promise<{ claims: PatramClaim[], diagnostics: PatramDiagnostic[] }>}
  */
-async function collectClaims(source_file_paths, project_directory) {
+async function collectClaims(
+  repo_config,
+  source_file_paths,
+  project_directory,
+) {
   /** @type {PatramClaim[]} */
   const claims = [];
   /** @type {PatramDiagnostic[]} */
   const diagnostics = [];
+  const parse_options = createParseOptions(repo_config);
 
   for (const source_file_path of source_file_paths) {
     const source_text = await readFile(
       resolve(project_directory, source_file_path),
       'utf8',
     );
-    const parse_result = parseSourceFile({
-      path: source_file_path,
-      source: source_text,
-    });
+    const parse_result = parseSourceFile(
+      {
+        path: source_file_path,
+        source: source_text,
+      },
+      parse_options,
+    );
 
     claims.push(...parse_result.claims);
     diagnostics.push(...parse_result.diagnostics);