patram 0.11.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (110) hide show
  1. package/bin/patram.js +4 -4
  2. package/lib/cli/commands/fields.js +0 -4
  3. package/lib/cli/commands/queries.js +10 -20
  4. package/lib/cli/commands/query.js +1 -8
  5. package/lib/cli/commands/refs.js +3 -10
  6. package/lib/cli/commands/show.js +1 -8
  7. package/lib/cli/help-metadata.js +71 -106
  8. package/lib/cli/main.js +10 -10
  9. package/lib/cli/parse-arguments-helpers.js +165 -59
  10. package/lib/cli/parse-arguments.js +4 -4
  11. package/lib/cli/render-help.js +2 -2
  12. package/lib/config/defaults.js +33 -25
  13. package/lib/config/load-patram-config.d.ts +8 -33
  14. package/lib/config/load-patram-config.js +9 -33
  15. package/lib/config/load-patram-config.types.d.ts +3 -40
  16. package/lib/config/manage-stored-queries-helpers.d.ts +4 -4
  17. package/lib/config/manage-stored-queries-helpers.js +91 -33
  18. package/lib/config/manage-stored-queries.d.ts +4 -4
  19. package/lib/config/manage-stored-queries.js +11 -5
  20. package/lib/config/patram-config.d.ts +34 -34
  21. package/lib/config/patram-config.js +3 -3
  22. package/lib/config/patram-config.types.d.ts +5 -11
  23. package/lib/config/resolve-patram-graph-config.d.ts +5 -1
  24. package/lib/config/resolve-patram-graph-config.js +3 -119
  25. package/lib/config/schema.d.ts +158 -269
  26. package/lib/config/schema.js +72 -210
  27. package/lib/config/validate-patram-config-value.js +6 -31
  28. package/lib/config/validation.d.ts +2 -12
  29. package/lib/config/validation.js +125 -483
  30. package/lib/find-close-match.d.ts +4 -1
  31. package/lib/graph/build-graph-identity.d.ts +1 -32
  32. package/lib/graph/build-graph-identity.js +5 -269
  33. package/lib/graph/build-graph.d.ts +13 -4
  34. package/lib/graph/build-graph.js +347 -488
  35. package/lib/graph/build-graph.types.d.ts +8 -9
  36. package/lib/graph/check-directive-metadata-helpers.d.ts +30 -0
  37. package/lib/graph/check-directive-metadata-helpers.js +126 -0
  38. package/lib/graph/check-directive-metadata.d.ts +8 -9
  39. package/lib/graph/check-directive-metadata.js +70 -561
  40. package/lib/graph/check-directive-path-target.d.ts +6 -13
  41. package/lib/graph/check-directive-path-target.js +26 -57
  42. package/lib/graph/check-directive-value.d.ts +1 -5
  43. package/lib/graph/check-directive-value.js +40 -180
  44. package/lib/graph/check-graph.d.ts +5 -5
  45. package/lib/graph/check-graph.js +8 -6
  46. package/lib/graph/document-node-identity.d.ts +23 -7
  47. package/lib/graph/document-node-identity.js +417 -160
  48. package/lib/graph/graph-node.d.ts +42 -0
  49. package/lib/graph/graph-node.js +83 -0
  50. package/lib/graph/inspect-reverse-references.js +16 -11
  51. package/lib/graph/load-project-graph.d.ts +7 -7
  52. package/lib/graph/load-project-graph.js +7 -7
  53. package/lib/graph/parse-where-clause.types.d.ts +3 -2
  54. package/lib/graph/query/cypher-reader.d.ts +59 -0
  55. package/lib/graph/query/cypher-reader.js +151 -0
  56. package/lib/graph/query/cypher-support.d.ts +79 -0
  57. package/lib/graph/query/cypher-support.js +213 -0
  58. package/lib/graph/query/cypher-tokenize.d.ts +13 -0
  59. package/lib/graph/query/cypher-tokenize.js +225 -0
  60. package/lib/graph/query/cypher.types.d.ts +43 -0
  61. package/lib/graph/query/execute.d.ts +7 -7
  62. package/lib/graph/query/execute.js +71 -33
  63. package/lib/graph/query/inspect.js +58 -24
  64. package/lib/graph/query/parse-cypher-patterns.d.ts +27 -0
  65. package/lib/graph/query/parse-cypher-patterns.js +382 -0
  66. package/lib/graph/query/parse-cypher.d.ts +7 -0
  67. package/lib/graph/query/parse-cypher.js +580 -0
  68. package/lib/graph/query/parse-query.d.ts +13 -0
  69. package/lib/graph/query/parse-query.js +97 -0
  70. package/lib/graph/query/resolve.js +77 -23
  71. package/lib/output/command-output.js +12 -5
  72. package/lib/output/compact-layout.js +221 -0
  73. package/lib/output/format-output-item-block.js +31 -1
  74. package/lib/output/format-output-metadata.js +16 -29
  75. package/lib/output/format-stored-query-block.js +95 -0
  76. package/lib/output/layout-incoming-references.js +101 -19
  77. package/lib/output/layout-stored-queries.js +23 -330
  78. package/lib/output/list-queries.js +1 -1
  79. package/lib/output/render-field-discovery.js +11 -2
  80. package/lib/output/render-output-view.js +9 -5
  81. package/lib/output/renderers/json.js +5 -26
  82. package/lib/output/renderers/plain.js +155 -35
  83. package/lib/output/renderers/rich.js +250 -36
  84. package/lib/output/resolved-link-layout.js +43 -0
  85. package/lib/output/rich-source/render.js +193 -35
  86. package/lib/output/show-document.js +25 -18
  87. package/lib/output/view-model/index.js +124 -103
  88. package/lib/parse/jsdoc/parse-jsdoc-blocks.js +1 -1
  89. package/lib/parse/jsdoc/parse-jsdoc-claims.js +12 -6
  90. package/lib/parse/markdown/parse-markdown-claims.js +99 -62
  91. package/lib/parse/markdown/parse-markdown-directives.d.ts +10 -6
  92. package/lib/parse/markdown/parse-markdown-directives.js +104 -18
  93. package/lib/parse/markdown/parse-markdown-prose.d.ts +27 -0
  94. package/lib/parse/markdown/parse-markdown-prose.js +243 -0
  95. package/lib/parse/parse-claims.d.ts +2 -6
  96. package/lib/parse/parse-claims.js +11 -53
  97. package/lib/parse/tagged-fenced/tagged-fenced-blocks.d.ts +4 -4
  98. package/lib/parse/tagged-fenced/tagged-fenced-blocks.js +4 -4
  99. package/lib/parse/yaml/parse-yaml-claims.js +4 -4
  100. package/lib/patram.d.ts +3 -5
  101. package/lib/patram.js +1 -1
  102. package/lib/scan/discover-fields.js +194 -55
  103. package/lib/scan/list-source-files.d.ts +4 -4
  104. package/lib/scan/list-source-files.js +4 -4
  105. package/package.json +1 -1
  106. package/lib/directive-validation-test-helpers.js +0 -87
  107. package/lib/graph/query/parse.d.ts +0 -75
  108. package/lib/graph/query/parse.js +0 -1064
  109. package/lib/output/derived-summary.js +0 -280
  110. package/lib/output/format-derived-summary-row.js +0 -9
@@ -1,32 +1,25 @@
1
1
  /**
2
2
  * @param {PatramClaim} claim
3
3
  * @param {string} directive_name
4
- * @param {MappingDefinition | null} mapping_definition
5
- * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }> | undefined} type_definition
4
+ * @param {MetadataFieldConfig | undefined} type_definition
6
5
  * @param {Map<string, string>} document_entity_keys
7
6
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
8
7
  * @param {Set<string>} document_paths
9
8
  * @returns {PatramDiagnostic[]}
10
9
  */
11
- export function createPathExistenceDiagnostics(claim: PatramClaim, directive_name: string, mapping_definition: MappingDefinition | null, type_definition: Exclude<DirectiveTypeConfig, {
12
- type: "enum";
13
- }> | undefined, document_entity_keys: Map<string, string>, document_node_references: Map<string, import("./document-node-identity.js").DocumentNodeReference>, document_paths: Set<string>): PatramDiagnostic[];
10
+ export function createPathExistenceDiagnostics(claim: PatramClaim, directive_name: string, type_definition: MetadataFieldConfig | undefined, document_entity_keys: Map<string, string>, document_node_references: Map<string, import("./document-node-identity.js").DocumentNodeReference>, document_paths: Set<string>): PatramDiagnostic[];
14
11
  /**
15
12
  * @param {PatramClaim} claim
16
13
  * @param {string} directive_name
17
- * @param {Record<string, MappingDefinition>} mappings
18
- * @param {PatramRepoConfig} repo_config
19
- * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }>} type_definition
14
+ * @param {Extract<MetadataFieldConfig, { type: 'ref' }>} type_definition
20
15
  * @param {Map<string, string>} document_entity_keys
21
16
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
22
17
  * @param {Set<string>} document_paths
23
18
  * @returns {PatramDiagnostic[]}
24
19
  */
25
- export function createPathClassDiagnostics(claim: PatramClaim, directive_name: string, mappings: Record<string, MappingDefinition>, repo_config: PatramRepoConfig, type_definition: Exclude<DirectiveTypeConfig, {
26
- type: "enum";
20
+ export function createTargetTypeDiagnostics(claim: PatramClaim, directive_name: string, type_definition: Extract<MetadataFieldConfig, {
21
+ type: "ref";
27
22
  }>, document_entity_keys: Map<string, string>, document_node_references: Map<string, import("./document-node-identity.js").DocumentNodeReference>, document_paths: Set<string>): PatramDiagnostic[];
28
23
  import type { PatramClaim } from '../parse/parse-claims.types.d.ts';
29
- import type { MappingDefinition } from '../config/patram-config.types.d.ts';
30
- import type { DirectiveTypeConfig } from '../config/load-patram-config.types.d.ts';
24
+ import type { MetadataFieldConfig } from '../config/load-patram-config.types.d.ts';
31
25
  import type { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';
32
- import type { PatramRepoConfig } from '../config/load-patram-config.types.d.ts';
@@ -1,7 +1,6 @@
1
1
  /**
2
- * @import { DirectiveTypeConfig, PatramDiagnostic, PatramRepoConfig } from '../config/load-patram-config.types.ts';
2
+ * @import { MetadataFieldConfig, PatramDiagnostic } from '../config/load-patram-config.types.ts';
3
3
  * @import { PatramClaim } from '../parse/parse-claims.types.ts';
4
- * @import { MappingDefinition } from '../config/patram-config.types.ts';
5
4
  */
6
5
 
7
6
  import { isPathLikeTarget } from '../parse/claim-helpers.js';
@@ -11,8 +10,7 @@ import { createOriginDiagnostic } from './directive-diagnostics.js';
11
10
  /**
12
11
  * @param {PatramClaim} claim
13
12
  * @param {string} directive_name
14
- * @param {MappingDefinition | null} mapping_definition
15
- * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }> | undefined} type_definition
13
+ * @param {MetadataFieldConfig | undefined} type_definition
16
14
  * @param {Map<string, string>} document_entity_keys
17
15
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
18
16
  * @param {Set<string>} document_paths
@@ -21,7 +19,6 @@ import { createOriginDiagnostic } from './directive-diagnostics.js';
21
19
  export function createPathExistenceDiagnostics(
22
20
  claim,
23
21
  directive_name,
24
- mapping_definition,
25
22
  type_definition,
26
23
  document_entity_keys,
27
24
  document_node_references,
@@ -30,14 +27,14 @@ export function createPathExistenceDiagnostics(
30
27
  if (
31
28
  typeof claim.value !== 'string' ||
32
29
  !isPathLikeTarget(claim.value) ||
33
- !shouldCheckDirectivePathExistence(mapping_definition, type_definition)
30
+ !shouldCheckDirectivePathExistence(type_definition)
34
31
  ) {
35
32
  return [];
36
33
  }
37
34
 
38
35
  const resolved_target = resolveDirectiveTargetPath(
39
36
  claim,
40
- mapping_definition,
37
+ type_definition,
41
38
  document_entity_keys,
42
39
  document_node_references,
43
40
  document_paths,
@@ -59,49 +56,41 @@ export function createPathExistenceDiagnostics(
59
56
  /**
60
57
  * @param {PatramClaim} claim
61
58
  * @param {string} directive_name
62
- * @param {Record<string, MappingDefinition>} mappings
63
- * @param {PatramRepoConfig} repo_config
64
- * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }>} type_definition
59
+ * @param {Extract<MetadataFieldConfig, { type: 'ref' }>} type_definition
65
60
  * @param {Map<string, string>} document_entity_keys
66
61
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
67
62
  * @param {Set<string>} document_paths
68
63
  * @returns {PatramDiagnostic[]}
69
64
  */
70
- export function createPathClassDiagnostics(
65
+ export function createTargetTypeDiagnostics(
71
66
  claim,
72
67
  directive_name,
73
- mappings,
74
- repo_config,
75
68
  type_definition,
76
69
  document_entity_keys,
77
70
  document_node_references,
78
71
  document_paths,
79
72
  ) {
80
- if (type_definition.type !== 'path' || !type_definition.path_class) {
73
+ if (typeof claim.value !== 'string' || !isPathLikeTarget(claim.value)) {
81
74
  return [];
82
75
  }
83
76
 
84
- const path_class_definition =
85
- repo_config.path_classes?.[type_definition.path_class];
86
-
87
- if (!path_class_definition) {
88
- return [];
89
- }
90
-
91
- const mapping_definition = resolveDirectiveMapping(mappings, claim);
92
77
  const resolved_target = resolveDirectiveTargetPath(
93
78
  claim,
94
- mapping_definition,
79
+ type_definition,
95
80
  document_entity_keys,
96
81
  document_node_references,
97
82
  document_paths,
98
83
  );
99
84
 
85
+ if (!resolved_target || !document_paths.has(resolved_target)) {
86
+ return [];
87
+ }
88
+
89
+ const target_reference = document_node_references.get(resolved_target);
90
+
100
91
  if (
101
- !resolved_target ||
102
- path_class_definition.prefixes.some((prefix) =>
103
- resolved_target.startsWith(prefix),
104
- )
92
+ type_definition.to === 'document' ||
93
+ target_reference?.class_name === type_definition.to
105
94
  ) {
106
95
  return [];
107
96
  }
@@ -109,15 +98,15 @@ export function createPathClassDiagnostics(
109
98
  return [
110
99
  createOriginDiagnostic(
111
100
  claim,
112
- 'directive.invalid_path_class',
113
- `Directive "${directive_name}" must point to path class "${type_definition.path_class}".`,
101
+ 'directive.invalid_target_type',
102
+ `Directive "${directive_name}" must point to type "${type_definition.to}".`,
114
103
  ),
115
104
  ];
116
105
  }
117
106
 
118
107
  /**
119
108
  * @param {PatramClaim} claim
120
- * @param {MappingDefinition | null} mapping_definition
109
+ * @param {MetadataFieldConfig | undefined} type_definition
121
110
  * @param {Map<string, string>} document_entity_keys
122
111
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
123
112
  * @param {Set<string>} document_paths
@@ -125,14 +114,15 @@ export function createPathClassDiagnostics(
125
114
  */
126
115
  function resolveDirectiveTargetPath(
127
116
  claim,
128
- mapping_definition,
117
+ type_definition,
129
118
  document_entity_keys,
130
119
  document_node_references,
131
120
  document_paths,
132
121
  ) {
133
- const target_kind = mapping_definition?.emit?.target_class ?? 'document';
122
+ const target_type =
123
+ type_definition?.type === 'ref' ? type_definition.to : 'document';
134
124
  const resolved_target = resolveTargetReference(
135
- target_kind,
125
+ target_type,
136
126
  'path',
137
127
  claim,
138
128
  document_entity_keys,
@@ -144,30 +134,9 @@ function resolveDirectiveTargetPath(
144
134
  }
145
135
 
146
136
  /**
147
- * @param {Record<string, MappingDefinition>} mappings
148
- * @param {PatramClaim} claim
149
- * @returns {MappingDefinition | null}
150
- */
151
- function resolveDirectiveMapping(mappings, claim) {
152
- if (!claim.name || !claim.parser) {
153
- return null;
154
- }
155
-
156
- return mappings[`${claim.parser}.directive.${claim.name}`] ?? null;
157
- }
158
-
159
- /**
160
- * @param {MappingDefinition | null} mapping_definition
161
- * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }> | undefined} type_definition
137
+ * @param {MetadataFieldConfig | undefined} type_definition
162
138
  * @returns {boolean}
163
139
  */
164
- function shouldCheckDirectivePathExistence(
165
- mapping_definition,
166
- type_definition,
167
- ) {
168
- if (type_definition?.type === 'path') {
169
- return true;
170
- }
171
-
172
- return mapping_definition?.emit?.target === 'path';
140
+ function shouldCheckDirectivePathExistence(type_definition) {
141
+ return type_definition?.type === 'path' || type_definition?.type === 'ref';
173
142
  }
@@ -3,17 +3,13 @@
3
3
  *
4
4
  * @param {PatramClaim} claim
5
5
  * @param {string} directive_name
6
- * @param {Record<string, MappingDefinition>} mappings
7
6
  * @param {PatramRepoConfig} repo_config
8
- * @param {MetadataDirectiveRuleConfig | undefined} _directive_rule
9
7
  * @param {Map<string, string>} document_entity_keys
10
8
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
11
9
  * @param {Set<string>} document_paths
12
10
  * @returns {PatramDiagnostic[]}
13
11
  */
14
- export function checkDirectiveValue(claim: PatramClaim, directive_name: string, mappings: Record<string, MappingDefinition>, repo_config: PatramRepoConfig, _directive_rule: MetadataDirectiveRuleConfig | undefined, document_entity_keys: Map<string, string>, document_node_references: Map<string, import("./document-node-identity.js").DocumentNodeReference>, document_paths: Set<string>): PatramDiagnostic[];
12
+ export function checkDirectiveValue(claim: PatramClaim, directive_name: string, repo_config: PatramRepoConfig, document_entity_keys: Map<string, string>, document_node_references: Map<string, import("./document-node-identity.js").DocumentNodeReference>, document_paths: Set<string>): PatramDiagnostic[];
15
13
  import type { PatramClaim } from '../parse/parse-claims.types.d.ts';
16
- import type { MappingDefinition } from '../config/patram-config.types.d.ts';
17
14
  import type { PatramRepoConfig } from '../config/load-patram-config.types.d.ts';
18
- import type { MetadataDirectiveRuleConfig } from '../config/load-patram-config.types.d.ts';
19
15
  import type { PatramDiagnostic } from '../config/load-patram-config.types.d.ts';
@@ -1,12 +1,11 @@
1
1
  /**
2
- * @import { DirectiveTypeConfig, MetadataDirectiveRuleConfig, PatramDiagnostic, PatramRepoConfig } from '../config/load-patram-config.types.ts';
2
+ * @import { MetadataFieldConfig, PatramDiagnostic, PatramRepoConfig } from '../config/load-patram-config.types.ts';
3
3
  * @import { PatramClaim } from '../parse/parse-claims.types.ts';
4
- * @import { MappingDefinition } from '../config/patram-config.types.ts';
5
4
  */
6
5
 
7
6
  import {
8
- createPathClassDiagnostics,
9
7
  createPathExistenceDiagnostics,
8
+ createTargetTypeDiagnostics,
10
9
  } from './check-directive-path-target.js';
11
10
  import { createOriginDiagnostic } from './directive-diagnostics.js';
12
11
  import {
@@ -20,9 +19,7 @@ import {
20
19
  *
21
20
  * @param {PatramClaim} claim
22
21
  * @param {string} directive_name
23
- * @param {Record<string, MappingDefinition>} mappings
24
22
  * @param {PatramRepoConfig} repo_config
25
- * @param {MetadataDirectiveRuleConfig | undefined} _directive_rule
26
23
  * @param {Map<string, string>} document_entity_keys
27
24
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
28
25
  * @param {Set<string>} document_paths
@@ -31,106 +28,38 @@ import {
31
28
  export function checkDirectiveValue(
32
29
  claim,
33
30
  directive_name,
34
- mappings,
35
31
  repo_config,
36
- _directive_rule,
37
32
  document_entity_keys,
38
33
  document_node_references,
39
34
  document_paths,
40
35
  ) {
41
- const mapping_definition = resolveDirectiveMapping(mappings, claim);
42
- const validation_field_name = getDirectiveValidationFieldName(
43
- directive_name,
44
- mapping_definition,
45
- );
46
- if (!validation_field_name || typeof claim.value !== 'string') {
36
+ if (!directive_name || typeof claim.value !== 'string') {
47
37
  return [];
48
38
  }
49
- const directive_value = claim.value;
50
- if (validation_field_name === '$class') {
51
- return checkClassValue(claim, directive_name, directive_value, repo_config);
52
- }
53
- const type_definition = repo_config.fields?.[validation_field_name];
54
- if (isStructuralDirectiveField(validation_field_name) || !type_definition) {
55
- return collectUntypedPathDiagnostics(
56
- claim,
57
- directive_name,
58
- mapping_definition,
59
- document_entity_keys,
60
- document_node_references,
61
- document_paths,
62
- );
63
- }
64
- return checkTypedDirectiveValue(
65
- claim,
66
- directive_name,
67
- directive_value,
68
- mappings,
69
- repo_config,
70
- mapping_definition,
71
- type_definition,
72
- document_entity_keys,
73
- document_node_references,
74
- document_paths,
75
- );
76
- }
77
39
 
78
- /**
79
- * @param {PatramClaim} claim
80
- * @param {string} directive_name
81
- * @param {string} class_name
82
- * @param {PatramRepoConfig} repo_config
83
- * @returns {PatramDiagnostic[]}
84
- */
85
- function checkClassValue(claim, directive_name, class_name, repo_config) {
86
- if (repo_config.classes?.[class_name] !== undefined) {
40
+ if (directive_name === 'title' || directive_name === 'description') {
87
41
  return [];
88
42
  }
89
43
 
90
- return [
91
- createOriginDiagnostic(
92
- claim,
93
- 'directive.invalid_enum',
94
- `Directive "${directive_name}" must reference a configured class.`,
95
- ),
96
- ];
97
- }
44
+ const type_definition = repo_config.fields?.[directive_name];
45
+
46
+ if (!type_definition) {
47
+ return [];
48
+ }
98
49
 
99
- /**
100
- * @param {PatramClaim} claim
101
- * @param {string} directive_name
102
- * @param {string} directive_value
103
- * @param {Record<string, MappingDefinition>} mappings
104
- * @param {PatramRepoConfig} repo_config
105
- * @param {MappingDefinition | null} mapping_definition
106
- * @param {DirectiveTypeConfig} type_definition
107
- * @param {Map<string, string>} document_entity_keys
108
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
109
- * @param {Set<string>} document_paths
110
- * @returns {PatramDiagnostic[]}
111
- */
112
- function checkTypedDirectiveValue(
113
- claim,
114
- directive_name,
115
- directive_value,
116
- mappings,
117
- repo_config,
118
- mapping_definition,
119
- type_definition,
120
- document_entity_keys,
121
- document_node_references,
122
- document_paths,
123
- ) {
124
50
  if (type_definition.type === 'enum') {
125
51
  return checkEnumValue(
126
52
  claim,
127
53
  directive_name,
128
- directive_value,
54
+ claim.value,
129
55
  type_definition.values,
130
56
  );
131
57
  }
132
58
 
133
- if (!isDirectiveValueValid(type_definition, directive_value)) {
59
+ if (
60
+ type_definition.type !== 'ref' &&
61
+ !isDirectiveValueValid(type_definition, claim.value)
62
+ ) {
134
63
  return [
135
64
  createOriginDiagnostic(
136
65
  claim,
@@ -143,9 +72,6 @@ function checkTypedDirectiveValue(
143
72
  return collectPathDiagnostics(
144
73
  claim,
145
74
  directive_name,
146
- mappings,
147
- repo_config,
148
- mapping_definition,
149
75
  type_definition,
150
76
  document_entity_keys,
151
77
  document_node_references,
@@ -156,38 +82,33 @@ function checkTypedDirectiveValue(
156
82
  /**
157
83
  * @param {PatramClaim} claim
158
84
  * @param {string} directive_name
159
- * @param {MappingDefinition | null} mapping_definition
160
- * @param {Map<string, string>} document_entity_keys
161
- * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
162
- * @param {Set<string>} document_paths
85
+ * @param {string} directive_value
86
+ * @param {string[]} allowed_values
163
87
  * @returns {PatramDiagnostic[]}
164
88
  */
165
- function collectUntypedPathDiagnostics(
89
+ function checkEnumValue(
166
90
  claim,
167
91
  directive_name,
168
- mapping_definition,
169
- document_entity_keys,
170
- document_node_references,
171
- document_paths,
92
+ directive_value,
93
+ allowed_values,
172
94
  ) {
173
- return createPathExistenceDiagnostics(
174
- claim,
175
- directive_name,
176
- mapping_definition,
177
- undefined,
178
- document_entity_keys,
179
- document_node_references,
180
- document_paths,
181
- );
95
+ if (allowed_values.includes(directive_value)) {
96
+ return [];
97
+ }
98
+
99
+ return [
100
+ createOriginDiagnostic(
101
+ claim,
102
+ 'directive.invalid_enum',
103
+ `Directive "${directive_name}" must be one of ${formatQuotedList(allowed_values)}.`,
104
+ ),
105
+ ];
182
106
  }
183
107
 
184
108
  /**
185
109
  * @param {PatramClaim} claim
186
110
  * @param {string} directive_name
187
- * @param {Record<string, MappingDefinition>} mappings
188
- * @param {PatramRepoConfig} repo_config
189
- * @param {MappingDefinition | null} mapping_definition
190
- * @param {Exclude<DirectiveTypeConfig, { type: 'enum' }>} type_definition
111
+ * @param {MetadataFieldConfig} type_definition
191
112
  * @param {Map<string, string>} document_entity_keys
192
113
  * @param {Map<string, import('./document-node-identity.js').DocumentNodeReference>} document_node_references
193
114
  * @param {Set<string>} document_paths
@@ -196,28 +117,28 @@ function collectUntypedPathDiagnostics(
196
117
  function collectPathDiagnostics(
197
118
  claim,
198
119
  directive_name,
199
- mappings,
200
- repo_config,
201
- mapping_definition,
202
120
  type_definition,
203
121
  document_entity_keys,
204
122
  document_node_references,
205
123
  document_paths,
206
124
  ) {
207
- return createPathClassDiagnostics(
125
+ const diagnostics = createPathExistenceDiagnostics(
208
126
  claim,
209
127
  directive_name,
210
- mappings,
211
- repo_config,
212
128
  type_definition,
213
129
  document_entity_keys,
214
130
  document_node_references,
215
131
  document_paths,
216
- ).concat(
217
- createPathExistenceDiagnostics(
132
+ );
133
+
134
+ if (type_definition.type !== 'ref') {
135
+ return diagnostics;
136
+ }
137
+
138
+ return diagnostics.concat(
139
+ createTargetTypeDiagnostics(
218
140
  claim,
219
141
  directive_name,
220
- mapping_definition,
221
142
  type_definition,
222
143
  document_entity_keys,
223
144
  document_node_references,
@@ -225,64 +146,3 @@ function collectPathDiagnostics(
225
146
  ),
226
147
  );
227
148
  }
228
-
229
- /**
230
- * @param {PatramClaim} claim
231
- * @param {string} directive_name
232
- * @param {string} directive_value
233
- * @param {string[]} allowed_values
234
- * @returns {PatramDiagnostic[]}
235
- */
236
- function checkEnumValue(
237
- claim,
238
- directive_name,
239
- directive_value,
240
- allowed_values,
241
- ) {
242
- if (allowed_values.includes(directive_value)) {
243
- return [];
244
- }
245
-
246
- return [
247
- createOriginDiagnostic(
248
- claim,
249
- 'directive.invalid_enum',
250
- `Directive "${directive_name}" must be one of ${formatQuotedList(allowed_values)}.`,
251
- ),
252
- ];
253
- }
254
-
255
- /**
256
- * @param {Record<string, MappingDefinition>} mappings
257
- * @param {PatramClaim} claim
258
- * @returns {MappingDefinition | null}
259
- */
260
- function resolveDirectiveMapping(mappings, claim) {
261
- if (!claim.name || !claim.parser) {
262
- return null;
263
- }
264
-
265
- return mappings[`${claim.parser}.directive.${claim.name}`] ?? null;
266
- }
267
-
268
- /**
269
- * @param {string} directive_name
270
- * @param {MappingDefinition | null} mapping_definition
271
- * @returns {string}
272
- */
273
- function getDirectiveValidationFieldName(directive_name, mapping_definition) {
274
- return mapping_definition?.node?.field ?? directive_name;
275
- }
276
-
277
- /**
278
- * @param {string} field_name
279
- * @returns {boolean}
280
- */
281
- function isStructuralDirectiveField(field_name) {
282
- return (
283
- field_name === '$class' ||
284
- field_name === '$id' ||
285
- field_name === '$path' ||
286
- field_name === 'title'
287
- );
288
- }
@@ -4,11 +4,11 @@
4
4
  * Reports broken document links and missing edge nodes after graph
5
5
  * materialization.
6
6
  *
7
- * Kind: graph
8
- * Status: active
9
- * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
10
- * Decided by: ../../docs/decisions/check-link-target-existence.md
11
- * Implements: ../../docs/tasks/v0/check-command.md
7
+ * kind: graph
8
+ * status: active
9
+ * tracked_in: ../../docs/plans/v0/source-anchor-dogfooding.md
10
+ * decided_by: ../../docs/decisions/check-link-target-existence.md
11
+ * implements: ../../docs/tasks/v0/check-command.md
12
12
  * @see {@link ../../docs/decisions/check-link-target-existence.md}
13
13
  * @patram
14
14
  * @see {@link ./build-graph.js}
@@ -4,6 +4,8 @@
4
4
  * @import { PatramClaim } from '../parse/parse-claims.types.ts';
5
5
  */
6
6
 
7
+ import { getGraphNodePath } from './graph-node.js';
8
+
7
9
  import { checkDirectiveMetadata } from './check-directive-metadata.js';
8
10
 
9
11
  /**
@@ -12,11 +14,11 @@ import { checkDirectiveMetadata } from './check-directive-metadata.js';
12
14
  * Reports broken document links and missing edge nodes after graph
13
15
  * materialization.
14
16
  *
15
- * Kind: graph
16
- * Status: active
17
- * Tracked in: ../../docs/plans/v0/source-anchor-dogfooding.md
18
- * Decided by: ../../docs/decisions/check-link-target-existence.md
19
- * Implements: ../../docs/tasks/v0/check-command.md
17
+ * kind: graph
18
+ * status: active
19
+ * tracked_in: ../../docs/plans/v0/source-anchor-dogfooding.md
20
+ * decided_by: ../../docs/decisions/check-link-target-existence.md
21
+ * implements: ../../docs/tasks/v0/check-command.md
20
22
  * @see {@link ../../docs/decisions/check-link-target-existence.md}
21
23
  * @patram
22
24
  * @see {@link ./build-graph.js}
@@ -118,7 +120,7 @@ function collectBrokenLinkDiagnostics(
118
120
  target_node,
119
121
  existing_file_path_set,
120
122
  ) {
121
- const target_path = target_node.$path ?? target_node.path;
123
+ const target_path = getGraphNodePath(target_node);
122
124
 
123
125
  if (graph_edge.relation !== 'links_to') {
124
126
  return;
@@ -9,27 +9,27 @@
9
9
  /**
10
10
  * Collect semantic entity keys defined by canonical documents.
11
11
  *
12
- * @param {Record<string, MappingDefinition>} mappings
12
+ * @param {PatramConfig} patram_config
13
13
  * @param {PatramClaim[]} claims
14
14
  * @returns {Map<string, string>}
15
15
  */
16
- export function collectDocumentEntityKeys(mappings: Record<string, MappingDefinition>, claims: PatramClaim[]): Map<string, string>;
16
+ export function collectDocumentEntityKeys(patram_config: PatramConfig, claims: PatramClaim[]): Map<string, string>;
17
17
  /**
18
18
  * Collect canonical graph identities for document-backed source paths.
19
19
  *
20
- * @param {Record<string, MappingDefinition>} mappings
20
+ * @param {PatramConfig} patram_config
21
21
  * @param {PatramClaim[]} claims
22
22
  * @returns {Map<string, DocumentNodeReference>}
23
23
  */
24
- export function collectDocumentNodeReferences(mappings: Record<string, MappingDefinition>, claims: PatramClaim[]): Map<string, DocumentNodeReference>;
24
+ export function collectDocumentNodeReferences(patram_config: PatramConfig, claims: PatramClaim[]): Map<string, DocumentNodeReference>;
25
25
  /**
26
26
  * Resolve the canonical node id for a source document path.
27
27
  *
28
- * @param {Record<string, string> | undefined} document_node_ids
28
+ * @param {Record<string, string> | undefined} document_path_ids
29
29
  * @param {string} document_path
30
30
  * @returns {string}
31
31
  */
32
- export function resolveDocumentNodeId(document_node_ids: Record<string, string> | undefined, document_path: string): string;
32
+ export function resolveDocumentNodeId(document_path_ids: Record<string, string> | undefined, document_path: string): string;
33
33
  /**
34
34
  * Normalize one repo-relative source path.
35
35
  *
@@ -37,11 +37,27 @@ export function resolveDocumentNodeId(document_node_ids: Record<string, string>
37
37
  * @returns {string}
38
38
  */
39
39
  export function normalizeRepoRelativePath(source_path: string): string;
40
+ /**
41
+ * Resolve one edge target key and canonical path.
42
+ *
43
+ * @param {string} target_class
44
+ * @param {'path' | 'value'} target_type
45
+ * @param {PatramClaim} claim
46
+ * @param {Map<string, string>} document_entity_keys
47
+ * @param {Map<string, DocumentNodeReference>} document_node_references
48
+ * @param {Set<string>} document_paths
49
+ * @returns {{ class_name: string, key: string, path?: string }}
50
+ */
51
+ export function resolveTargetReference(target_class: string, target_type: "path" | "value", claim: PatramClaim, document_entity_keys: Map<string, string>, document_node_references: Map<string, DocumentNodeReference>, document_paths: Set<string>): {
52
+ class_name: string;
53
+ key: string;
54
+ path?: string;
55
+ };
40
56
  export type DocumentNodeReference = {
41
57
  class_name: string;
42
58
  id: string;
43
59
  key: string;
44
60
  path: string;
45
61
  };
46
- import type { MappingDefinition } from '../config/patram-config.types.d.ts';
62
+ import type { PatramConfig } from '../config/patram-config.types.d.ts';
47
63
  import type { PatramClaim } from '../parse/parse-claims.types.d.ts';