patram 0.4.0 → 0.6.0

package/lib/build-graph-identity.js

@@ -1,5 +1,5 @@
-/** @import * as $k$$l$document$j$node$j$identity$k$js from './document-node-identity.js'; */
 /**
+ * @import { DocumentNodeReference } from './document-node-identity.js';
  * @import { GraphNode } from './build-graph.types.ts';
  * @import { PatramClaim } from './parse-claims.types.ts';
  */
@@ -48,7 +48,7 @@ export function resolveNodeKey(node_mapping, claim, document_entity_keys) {
  * @param {'path' | 'value'} target_type
  * @param {PatramClaim} claim
  * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Map<string, DocumentNodeReference>} document_node_references
  * @param {Set<string>} document_paths
  * @returns {{ class_name: string, key: string, path?: string }}
  */
@@ -124,7 +124,7 @@ function resolveValueTargetReference(target_kind, claim) {
  * @param {string} target_class
  * @param {PatramClaim} claim
  * @param {Map<string, string>} document_entity_keys
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Map<string, DocumentNodeReference>} document_node_references
  * @param {Set<string>} document_paths
  * @returns {{ class_name: string, key: string, path?: string }}
  */
@@ -171,7 +171,7 @@ function resolvePathTargetReference(
 
 /**
  * @param {string} target_path
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
+ * @param {Map<string, DocumentNodeReference>} document_node_references
  * @returns {{ class_name: string, key: string, path?: string }}
  */
 function resolveDocumentTargetReference(target_path, document_node_references) {
@@ -201,7 +201,14 @@ function resolveDocumentTargetReference(target_path, document_node_references) {
 function resolveDirectiveAwareTargetPath(claim, raw_target, document_paths) {
   const normalized_raw_target = normalizeRepoRelativePath(raw_target);
 
-  if (claim.type === 'directive' && document_paths.has(normalized_raw_target)) {
+  if (
+    claim.type === 'directive' &&
+    shouldKeepDirectiveTargetRepoRelative(
+      raw_target,
+      normalized_raw_target,
+      document_paths,
+    )
+  ) {
     return normalized_raw_target;
   }
 
@@ -212,6 +219,40 @@ function resolveDirectiveAwareTargetPath(claim, raw_target, document_paths) {
   return normalizeRepoRelativePath(posix.join(source_directory, raw_target));
 }
 
+/**
+ * @param {string} raw_target
+ * @param {string} normalized_raw_target
+ * @param {Set<string>} document_paths
+ * @returns {boolean}
+ */
+function shouldKeepDirectiveTargetRepoRelative(
+  raw_target,
+  normalized_raw_target,
+  document_paths,
+) {
+  if (raw_target.startsWith('./') || raw_target.startsWith('../')) {
+    return false;
+  }
+
+  if (document_paths.has(normalized_raw_target)) {
+    return true;
+  }
+
+  const target_root_segment = normalized_raw_target.split('/')[0];
+
+  if (!target_root_segment) {
+    return false;
+  }
+
+  for (const document_path of document_paths) {
+    if (document_path.split('/')[0] === target_root_segment) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * @param {PatramClaim} claim
  * @returns {string}
@@ -246,8 +287,8 @@ function getDocumentEntityMapKey(document_path, class_name) {
 }
 
 /**
- * @param {import('./document-node-identity.js').DocumentNodeReference | undefined} document_node_reference
- * @returns {document_node_reference is $k$$l$document$j$node$j$identity$k$js.DocumentNodeReference}
+ * @param {DocumentNodeReference | undefined} document_node_reference
+ * @returns {document_node_reference is DocumentNodeReference}
  */
 function documentNodeReferenceIsPromoted(document_node_reference) {
   return (

package/lib/build-graph.js

@@ -30,7 +30,7 @@ import {
  * Uses Term: ../docs/reference/terms/graph.md
  * Uses Term: ../docs/reference/terms/mapping.md
  * Uses Term: ../docs/reference/terms/relation.md
- * Tracked in: ../docs/plans/v0/source-anchor-dogfood.md
+ * Tracked in: ../docs/plans/v0/source-anchor-dogfooding.md
  * Decided by: ../docs/decisions/graph-materialization.md
  * Implements: ../docs/tasks/v0/materialize-graph.md
  * @patram
@@ -771,7 +771,7 @@ function getFieldDefinition(patram_config, field_name) {
  * @returns {{ fields?: Record<string, { presence: 'required' | 'optional' | 'forbidden' }>, unknown_fields?: 'ignore' | 'error' } | undefined}
  */
 function getClassSchema(patram_config, class_name) {
-  return patram_config.class_schemas?.[class_name];
+  return patram_config.classes[class_name]?.schema;
 }
 
 /**

package/lib/check-directive-metadata.js

@@ -17,6 +17,7 @@ import {
   createDocumentDiagnostic,
   createOriginDiagnostic,
 } from './directive-diagnostics.js';
+import { formatQuotedList } from './directive-type-rules.js';
 import { resolvePatramGraphConfig } from './resolve-patram-graph-config.js';
 
 /**
@@ -44,11 +45,7 @@ export function checkDirectiveMetadata(
   claims,
   existing_file_paths,
 ) {
-  if (
-    claims.length === 0 ||
-    (repo_config.fields === undefined &&
-      repo_config.class_schemas === undefined)
-  ) {
+  if (claims.length === 0 || !hasDirectiveValidationConfig(repo_config)) {
     return [];
   }
 
@@ -93,6 +90,19 @@ export function checkDirectiveMetadata(
   return diagnostics;
 }
 
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {boolean}
+ */
+function hasDirectiveValidationConfig(repo_config) {
+  return (
+    repo_config.fields !== undefined ||
+    hasMarkdownStyleValidationConfig(repo_config) ||
+    hasConfiguredClassSchemas(repo_config) ||
+    hasPathTargetDirectiveMappings(repo_config)
+  );
+}
+
 /**
  * @param {PatramClaim[]} claims
  * @returns {Map<string, PatramClaim[]>}
@@ -143,9 +153,11 @@ function collectDocumentDiagnostics(
   document_paths,
 ) {
   const document_kind = resolveDocumentKind(graph, document_path);
-  const schema_definition = repo_config.class_schemas?.[document_kind];
+  const schema_definition = repo_config.classes?.[document_kind]?.schema;
   /** @type {Map<string, number>} */
   const directive_counts = new Map();
+  /** @type {Set<string>} */
+  const seen_markdown_styles = new Set();
 
   for (const claim of document_claims) {
     if (!claim.name) {
@@ -160,6 +172,7 @@ function collectDocumentDiagnostics(
         document_kind,
         schema_definition,
         directive_counts,
+        seen_markdown_styles,
         document_entity_keys,
         document_node_references,
         document_paths,
@@ -185,6 +198,7 @@ function collectDocumentDiagnostics(
  * @param {string} document_kind
  * @param {MetadataSchemaConfig | undefined} schema_definition
  * @param {Map<string, number>} directive_counts
+ * @param {Set<string>} seen_markdown_styles
  * @param {Map<string, string>} document_entity_keys
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
  * @param {Set<string>} document_paths
@@ -197,6 +211,7 @@ function collectClaimDiagnostics(
   document_kind,
   schema_definition,
   directive_counts,
+  seen_markdown_styles,
   document_entity_keys,
   document_node_references,
   document_paths,
@@ -227,6 +242,12 @@ function collectClaimDiagnostics(
       schema_definition,
       next_count,
     ),
+    ...collectMarkdownStyleDiagnostics(
+      claim,
+      document_kind,
+      schema_definition,
+      seen_markdown_styles,
+    ),
     ...checkDirectiveValue(
       claim,
       claim.name,
@@ -240,6 +261,68 @@ function collectClaimDiagnostics(
   ];
 }
 
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {boolean}
+ */
+function hasConfiguredClassSchemas(repo_config) {
+  for (const class_definition of Object.values(repo_config.classes ?? {})) {
+    if (class_definition.schema) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {boolean}
+ */
+function hasMarkdownStyleValidationConfig(repo_config) {
+  for (const class_definition of Object.values(repo_config.classes ?? {})) {
+    const schema_definition = class_definition.schema;
+
+    if (!schema_definition) {
+      continue;
+    }
+
+    if (
+      schema_definition.markdown_styles !== undefined ||
+      schema_definition.mixed_styles !== undefined
+    ) {
+      return true;
+    }
+
+    for (const field_rule of Object.values(schema_definition.fields)) {
+      if (field_rule.markdown_styles !== undefined) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * @param {PatramRepoConfig} repo_config
+ * @returns {boolean}
+ */
+function hasPathTargetDirectiveMappings(repo_config) {
+  for (const [mapping_name, mapping_definition] of Object.entries(
+    repo_config.mappings ?? {},
+  )) {
+    if (
+      mapping_name.includes('.directive.') &&
+      mapping_definition.emit?.target === 'path'
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * @param {PatramRepoConfig} repo_config
  * @param {string} document_path
@@ -532,3 +615,89 @@ function collectPlacementDiagnostics(
     ),
   ];
 }
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} document_kind
+ * @param {MetadataSchemaConfig | undefined} schema_definition
+ * @param {Set<string>} seen_markdown_styles
+ * @returns {PatramDiagnostic[]}
+ */
+function collectMarkdownStyleDiagnostics(
+  claim,
+  document_kind,
+  schema_definition,
+  seen_markdown_styles,
+) {
+  const markdown_style = resolveClaimMarkdownStyle(claim);
+
+  if (!markdown_style || !claim.name) {
+    return [];
+  }
+
+  /** @type {PatramDiagnostic[]} */
+  const diagnostics = [];
+  const allowed_styles =
+    schema_definition?.fields[claim.name]?.markdown_styles ??
+    schema_definition?.markdown_styles;
+
+  if (allowed_styles && !allowed_styles.includes(markdown_style)) {
+    diagnostics.push(
+      createOriginDiagnostic(
+        claim,
+        'directive.invalid_style',
+        `Directive "${claim.name}" uses markdown style "${markdown_style}" but only ${formatQuotedList(allowed_styles)} are allowed.`,
+      ),
+    );
+  }
+
+  if (
+    shouldReportMixedStyles(
+      schema_definition,
+      seen_markdown_styles,
+      markdown_style,
+    )
+  ) {
+    diagnostics.push(
+      createOriginDiagnostic(
+        claim,
+        'document.mixed_styles',
+        `Document mixes markdown directive style "${markdown_style}" with ${formatQuotedList([...seen_markdown_styles])} while class "${document_kind}" sets mixed_styles="error".`,
+      ),
+    );
+  }
+
+  seen_markdown_styles.add(markdown_style);
+
+  return diagnostics;
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @returns {string | null}
+ */
+function resolveClaimMarkdownStyle(claim) {
+  if (claim.parser !== 'markdown' || claim.markdown_style === undefined) {
+    return null;
+  }
+
+  return claim.markdown_style;
+}
+
+/**
+ * @param {MetadataSchemaConfig | undefined} schema_definition
+ * @param {Set<string>} seen_markdown_styles
+ * @param {string} markdown_style
+ * @returns {boolean}
+ */
+function shouldReportMixedStyles(
+  schema_definition,
+  seen_markdown_styles,
+  markdown_style,
+) {
+  return (
+    schema_definition?.mixed_styles === 'error' &&
+    seen_markdown_styles.size === 1 &&
+    !seen_markdown_styles.has(markdown_style)
+  );
+}

package/lib/check-directive-path-target.js

@@ -0,0 +1,173 @@
+/**
+ * @import { DirectiveTypeConfig, PatramDiagnostic, PatramRepoConfig } from './load-patram-config.types.ts';
+ * @import { PatramClaim } from './parse-claims.types.ts';
+ * @import { MappingDefinition } from './patram-config.types.ts';
+ */
+
+import { isPathLikeTarget } from './claim-helpers.js';
+import { resolveTargetReference } from './build-graph-identity.js';
+import { createOriginDiagnostic } from './directive-diagnostics.js';
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {MappingDefinition | null} mapping_definition
+ * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }> | undefined} 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[]}
+ */
+export function createPathExistenceDiagnostics(
+  claim,
+  directive_name,
+  mapping_definition,
+  type_definition,
+  document_entity_keys,
+  document_node_references,
+  document_paths,
+) {
+  if (
+    typeof claim.value !== 'string' ||
+    !isPathLikeTarget(claim.value) ||
+    !shouldCheckDirectivePathExistence(mapping_definition, type_definition)
+  ) {
+    return [];
+  }
+
+  const resolved_target = resolveDirectiveTargetPath(
+    claim,
+    mapping_definition,
+    document_entity_keys,
+    document_node_references,
+    document_paths,
+  );
+
+  if (!resolved_target || document_paths.has(resolved_target)) {
+    return [];
+  }
+
+  return [
+    createOriginDiagnostic(
+      claim,
+      'directive.path_not_found',
+      `Directive "${directive_name}" points to missing file "${resolved_target}".`,
+    ),
+  ];
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @param {string} directive_name
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramRepoConfig} repo_config
+ * @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[]}
+ */
+export function createPathClassDiagnostics(
+  claim,
+  directive_name,
+  mappings,
+  repo_config,
+  type_definition,
+  document_entity_keys,
+  document_node_references,
+  document_paths,
+) {
+  if (type_definition.type !== 'path' || !type_definition.path_class) {
+    return [];
+  }
+
+  const path_class_definition =
+    repo_config.path_classes?.[type_definition.path_class];
+
+  if (!path_class_definition) {
+    return [];
+  }
+
+  const mapping_definition = resolveDirectiveMapping(mappings, claim);
+  const resolved_target = resolveDirectiveTargetPath(
+    claim,
+    mapping_definition,
+    document_entity_keys,
+    document_node_references,
+    document_paths,
+  );
+
+  if (
+    !resolved_target ||
+    path_class_definition.prefixes.some((prefix) =>
+      resolved_target.startsWith(prefix),
+    )
+  ) {
+    return [];
+  }
+
+  return [
+    createOriginDiagnostic(
+      claim,
+      'directive.invalid_path_class',
+      `Directive "${directive_name}" must point to path class "${type_definition.path_class}".`,
+    ),
+  ];
+}
+
+/**
+ * @param {PatramClaim} claim
+ * @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 {string | undefined}
+ */
+function resolveDirectiveTargetPath(
+  claim,
+  mapping_definition,
+  document_entity_keys,
+  document_node_references,
+  document_paths,
+) {
+  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,
+  );
+
+  return resolved_target.path;
+}
+
+/**
+ * @param {Record<string, MappingDefinition>} mappings
+ * @param {PatramClaim} claim
+ * @returns {MappingDefinition | null}
+ */
+function resolveDirectiveMapping(mappings, claim) {
+  if (!claim.name || !claim.parser) {
+    return null;
+  }
+
+  return mappings[`${claim.parser}.directive.${claim.name}`] ?? null;
+}
+
+/**
+ * @param {MappingDefinition | null} mapping_definition
+ * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }> | undefined} type_definition
+ * @returns {boolean}
+ */
+function shouldCheckDirectivePathExistence(
+  mapping_definition,
+  type_definition,
+) {
+  if (type_definition?.type === 'path') {
+    return true;
+  }
+
+  return mapping_definition?.emit?.target === 'path';
+}