@ontrails/warden 1.0.0-beta.3 → 1.0.0-beta.32

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 (260) hide show
  1. package/CHANGELOG.md +674 -9
  2. package/README.md +133 -26
  3. package/bin/warden.ts +51 -0
  4. package/package.json +28 -5
  5. package/src/adapter-check.ts +136 -0
  6. package/src/ast.ts +137 -0
  7. package/src/cli.ts +1451 -104
  8. package/src/command.ts +966 -0
  9. package/src/config.ts +193 -0
  10. package/src/draft.ts +22 -0
  11. package/src/drift.ts +122 -22
  12. package/src/fix.ts +120 -0
  13. package/src/formatters.ts +79 -9
  14. package/src/guide.ts +245 -0
  15. package/src/index.ts +217 -14
  16. package/src/project-context.ts +192 -0
  17. package/src/project-rules.ts +290 -0
  18. package/src/resolve.ts +531 -0
  19. package/src/rules/activation-orphan.ts +97 -0
  20. package/src/rules/ast.ts +4008 -86
  21. package/src/rules/circular-refs.ts +154 -0
  22. package/src/rules/cli-command-route-coherence.ts +177 -0
  23. package/src/rules/composes-declarations.ts +837 -0
  24. package/src/rules/context-no-surface-types.ts +78 -15
  25. package/src/rules/contour-exists.ts +251 -0
  26. package/src/rules/contour-ids.ts +15 -0
  27. package/src/rules/dead-internal-trail.ts +161 -0
  28. package/src/rules/dead-public-trail.ts +258 -0
  29. package/src/rules/draft-file-marking.ts +160 -0
  30. package/src/rules/draft-visible-debt.ts +87 -0
  31. package/src/rules/duplicate-public-contract.ts +91 -0
  32. package/src/rules/error-mapping-completeness.ts +290 -0
  33. package/src/rules/example-valid.ts +395 -0
  34. package/src/rules/fires-declarations.ts +735 -0
  35. package/src/rules/implementation-returns-result.ts +1409 -166
  36. package/src/rules/incomplete-accessor-for-standard-op.ts +272 -0
  37. package/src/rules/incomplete-crud.ts +581 -0
  38. package/src/rules/index.ts +235 -18
  39. package/src/rules/intent-propagation.ts +127 -0
  40. package/src/rules/layer-field-name-drift.ts +102 -0
  41. package/src/rules/library-projection-coherence.ts +100 -0
  42. package/src/rules/metadata.ts +755 -0
  43. package/src/rules/missing-reconcile.ts +98 -0
  44. package/src/rules/missing-visibility.ts +110 -0
  45. package/src/rules/no-destructured-compose.ts +194 -0
  46. package/src/rules/no-dev-permit-in-source.ts +99 -0
  47. package/src/rules/no-direct-implementation-call.ts +7 -7
  48. package/src/rules/no-legacy-layer-imports.ts +211 -0
  49. package/src/rules/no-native-error-result.ts +118 -0
  50. package/src/rules/no-redundant-result-error-wrap.ts +384 -0
  51. package/src/rules/no-retired-cross-vocabulary.ts +194 -0
  52. package/src/rules/no-sync-result-assumption.ts +1135 -98
  53. package/src/rules/no-throw-in-detour-recover.ts +225 -0
  54. package/src/rules/no-throw-in-implementation.ts +10 -9
  55. package/src/rules/no-top-level-surface.ts +371 -0
  56. package/src/rules/on-references-exist.ts +194 -0
  57. package/src/rules/orphaned-signal.ts +150 -0
  58. package/src/rules/owner-projection-parity.ts +143 -0
  59. package/src/rules/permit-governance.ts +25 -0
  60. package/src/rules/public-export-example-coverage.ts +562 -0
  61. package/src/rules/public-internal-deep-imports.ts +457 -0
  62. package/src/rules/public-output-schema.ts +29 -0
  63. package/src/rules/public-union-output-discriminants.ts +150 -0
  64. package/src/rules/read-intent-fires.ts +187 -0
  65. package/src/rules/reference-exists.ts +98 -0
  66. package/src/rules/registry-names.ts +155 -0
  67. package/src/rules/resolved-import-boundary.ts +146 -0
  68. package/src/rules/resource-declarations.ts +693 -0
  69. package/src/rules/resource-exists.ts +179 -0
  70. package/src/rules/resource-id-grammar.ts +65 -0
  71. package/src/rules/resource-mock-coverage.ts +115 -0
  72. package/src/rules/scan.ts +38 -25
  73. package/src/rules/scheduled-destroy-intent.ts +44 -0
  74. package/src/rules/signal-graph-coaching.ts +191 -0
  75. package/src/rules/specs.ts +9 -5
  76. package/src/rules/static-resource-accessor-preference.ts +649 -0
  77. package/src/rules/surface-facet-coherence.ts +362 -0
  78. package/src/rules/trail-fork-coaching.ts +616 -0
  79. package/src/rules/trail-versioning-source.ts +1072 -0
  80. package/src/rules/trail-versioning-topo.ts +172 -0
  81. package/src/rules/types.ts +297 -8
  82. package/src/rules/unmaterialized-activation-source.ts +84 -0
  83. package/src/rules/unreachable-detour-shadowing.ts +339 -0
  84. package/src/rules/valid-describe-refs.ts +162 -32
  85. package/src/rules/valid-detour-contract.ts +78 -0
  86. package/src/rules/warden-export-symmetry.ts +540 -0
  87. package/src/rules/warden-rules-use-ast.ts +1114 -0
  88. package/src/rules/webhook-route-collision.ts +243 -0
  89. package/src/trails/activation-orphan.trail.ts +84 -0
  90. package/src/trails/circular-refs.trail.ts +29 -0
  91. package/src/trails/cli-command-route-coherence.trail.ts +47 -0
  92. package/src/trails/composes-declarations.trail.ts +22 -0
  93. package/src/trails/context-no-surface-types.trail.ts +21 -0
  94. package/src/trails/contour-exists.trail.ts +21 -0
  95. package/src/trails/dead-internal-trail.trail.ts +26 -0
  96. package/src/trails/dead-public-trail.trail.ts +31 -0
  97. package/src/trails/deprecation-without-guidance.trail.ts +21 -0
  98. package/src/trails/draft-file-marking.trail.ts +16 -0
  99. package/src/trails/draft-visible-debt.trail.ts +16 -0
  100. package/src/trails/duplicate-public-contract.trail.ts +47 -0
  101. package/src/trails/error-mapping-completeness.trail.ts +30 -0
  102. package/src/trails/example-valid.trail.ts +25 -0
  103. package/src/trails/fires-declarations.trail.ts +23 -0
  104. package/src/trails/fork-without-preserved-blaze.trail.ts +31 -0
  105. package/src/trails/implementation-returns-result.trail.ts +20 -0
  106. package/src/trails/incomplete-accessor-for-standard-op.trail.ts +76 -0
  107. package/src/trails/incomplete-crud.trail.ts +39 -0
  108. package/src/trails/index.ts +83 -0
  109. package/src/trails/intent-propagation.trail.ts +30 -0
  110. package/src/trails/layer-field-name-drift.trail.ts +39 -0
  111. package/src/trails/library-projection-coherence.trail.ts +43 -0
  112. package/src/trails/marker-schema-unsupported.trail.ts +23 -0
  113. package/src/trails/missing-reconcile.trail.ts +33 -0
  114. package/src/trails/missing-visibility.trail.ts +22 -0
  115. package/src/trails/no-destructured-compose.trail.ts +44 -0
  116. package/src/trails/no-dev-permit-in-source.trail.ts +16 -0
  117. package/src/trails/no-direct-implementation-call.trail.ts +16 -0
  118. package/src/trails/no-legacy-layer-imports.trail.ts +41 -0
  119. package/src/trails/no-native-error-result.trail.ts +18 -0
  120. package/src/trails/no-redundant-result-error-wrap.trail.ts +55 -0
  121. package/src/trails/no-retired-cross-vocabulary.trail.ts +42 -0
  122. package/src/trails/no-sync-result-assumption.trail.ts +19 -0
  123. package/src/trails/no-throw-in-detour-recover.trail.ts +24 -0
  124. package/src/trails/no-throw-in-implementation.trail.ts +20 -0
  125. package/src/trails/no-top-level-surface.trail.ts +43 -0
  126. package/src/trails/on-references-exist.trail.ts +21 -0
  127. package/src/trails/orphaned-signal.trail.ts +36 -0
  128. package/src/trails/owner-projection-parity.trail.ts +26 -0
  129. package/src/trails/pending-force.trail.ts +21 -0
  130. package/src/trails/permit-governance.trail.ts +51 -0
  131. package/src/trails/prefer-schema-inference.trail.ts +21 -0
  132. package/src/trails/public-export-example-coverage.trail.ts +16 -0
  133. package/src/trails/public-internal-deep-imports.trail.ts +94 -0
  134. package/src/trails/public-output-schema.trail.ts +55 -0
  135. package/src/trails/public-union-output-discriminants.trail.ts +33 -0
  136. package/src/trails/read-intent-fires.trail.ts +20 -0
  137. package/src/trails/reference-exists.trail.ts +25 -0
  138. package/src/trails/resolved-import-boundary.trail.ts +109 -0
  139. package/src/trails/resource-declarations.trail.ts +25 -0
  140. package/src/trails/resource-exists.trail.ts +27 -0
  141. package/src/trails/resource-id-grammar.trail.ts +39 -0
  142. package/src/trails/resource-mock-coverage.trail.ts +40 -0
  143. package/src/trails/run.ts +162 -0
  144. package/src/trails/scheduled-destroy-intent.trail.ts +56 -0
  145. package/src/trails/schema.ts +198 -0
  146. package/src/trails/signal-graph-coaching.trail.ts +77 -0
  147. package/src/trails/static-resource-accessor-preference.trail.ts +25 -0
  148. package/src/trails/surface-facet-coherence.trail.ts +25 -0
  149. package/src/trails/topo.ts +6 -0
  150. package/src/trails/trail-fork-coaching.trail.ts +42 -0
  151. package/src/trails/unmaterialized-activation-source.trail.ts +72 -0
  152. package/src/trails/unreachable-detour-shadowing.trail.ts +45 -0
  153. package/src/trails/valid-describe-refs.trail.ts +18 -0
  154. package/src/trails/valid-detour-contract.trail.ts +71 -0
  155. package/src/trails/version-gap.trail.ts +35 -0
  156. package/src/trails/version-pinned-compose.trail.ts +23 -0
  157. package/src/trails/version-without-examples.trail.ts +38 -0
  158. package/src/trails/warden-export-symmetry.trail.ts +16 -0
  159. package/src/trails/warden-rules-use-ast.trail.ts +64 -0
  160. package/src/trails/webhook-route-collision.trail.ts +50 -0
  161. package/src/trails/wrap-rule.ts +214 -0
  162. package/src/workspaces.ts +199 -0
  163. package/.turbo/turbo-build.log +0 -1
  164. package/.turbo/turbo-lint.log +0 -3
  165. package/.turbo/turbo-typecheck.log +0 -1
  166. package/dist/cli.d.ts +0 -46
  167. package/dist/cli.d.ts.map +0 -1
  168. package/dist/cli.js +0 -221
  169. package/dist/cli.js.map +0 -1
  170. package/dist/drift.d.ts +0 -26
  171. package/dist/drift.d.ts.map +0 -1
  172. package/dist/drift.js +0 -27
  173. package/dist/drift.js.map +0 -1
  174. package/dist/formatters.d.ts +0 -29
  175. package/dist/formatters.d.ts.map +0 -1
  176. package/dist/formatters.js +0 -87
  177. package/dist/formatters.js.map +0 -1
  178. package/dist/index.d.ts +0 -26
  179. package/dist/index.d.ts.map +0 -1
  180. package/dist/index.js +0 -26
  181. package/dist/index.js.map +0 -1
  182. package/dist/rules/ast.d.ts +0 -41
  183. package/dist/rules/ast.d.ts.map +0 -1
  184. package/dist/rules/ast.js +0 -163
  185. package/dist/rules/ast.js.map +0 -1
  186. package/dist/rules/context-no-surface-types.d.ts +0 -12
  187. package/dist/rules/context-no-surface-types.d.ts.map +0 -1
  188. package/dist/rules/context-no-surface-types.js +0 -96
  189. package/dist/rules/context-no-surface-types.js.map +0 -1
  190. package/dist/rules/implementation-returns-result.d.ts +0 -13
  191. package/dist/rules/implementation-returns-result.d.ts.map +0 -1
  192. package/dist/rules/implementation-returns-result.js +0 -277
  193. package/dist/rules/implementation-returns-result.js.map +0 -1
  194. package/dist/rules/index.d.ts +0 -22
  195. package/dist/rules/index.d.ts.map +0 -1
  196. package/dist/rules/index.js +0 -41
  197. package/dist/rules/index.js.map +0 -1
  198. package/dist/rules/no-direct-impl-in-route.d.ts +0 -12
  199. package/dist/rules/no-direct-impl-in-route.d.ts.map +0 -1
  200. package/dist/rules/no-direct-impl-in-route.js +0 -46
  201. package/dist/rules/no-direct-impl-in-route.js.map +0 -1
  202. package/dist/rules/no-direct-implementation-call.d.ts +0 -12
  203. package/dist/rules/no-direct-implementation-call.d.ts.map +0 -1
  204. package/dist/rules/no-direct-implementation-call.js +0 -39
  205. package/dist/rules/no-direct-implementation-call.js.map +0 -1
  206. package/dist/rules/no-sync-result-assumption.d.ts +0 -6
  207. package/dist/rules/no-sync-result-assumption.d.ts.map +0 -1
  208. package/dist/rules/no-sync-result-assumption.js +0 -98
  209. package/dist/rules/no-sync-result-assumption.js.map +0 -1
  210. package/dist/rules/no-throw-in-detour-target.d.ts +0 -12
  211. package/dist/rules/no-throw-in-detour-target.d.ts.map +0 -1
  212. package/dist/rules/no-throw-in-detour-target.js +0 -87
  213. package/dist/rules/no-throw-in-detour-target.js.map +0 -1
  214. package/dist/rules/no-throw-in-implementation.d.ts +0 -9
  215. package/dist/rules/no-throw-in-implementation.d.ts.map +0 -1
  216. package/dist/rules/no-throw-in-implementation.js +0 -34
  217. package/dist/rules/no-throw-in-implementation.js.map +0 -1
  218. package/dist/rules/prefer-schema-inference.d.ts +0 -7
  219. package/dist/rules/prefer-schema-inference.d.ts.map +0 -1
  220. package/dist/rules/prefer-schema-inference.js +0 -86
  221. package/dist/rules/prefer-schema-inference.js.map +0 -1
  222. package/dist/rules/scan.d.ts +0 -8
  223. package/dist/rules/scan.d.ts.map +0 -1
  224. package/dist/rules/scan.js +0 -32
  225. package/dist/rules/scan.js.map +0 -1
  226. package/dist/rules/specs.d.ts +0 -29
  227. package/dist/rules/specs.d.ts.map +0 -1
  228. package/dist/rules/specs.js +0 -192
  229. package/dist/rules/specs.js.map +0 -1
  230. package/dist/rules/structure.d.ts +0 -13
  231. package/dist/rules/structure.d.ts.map +0 -1
  232. package/dist/rules/structure.js +0 -142
  233. package/dist/rules/structure.js.map +0 -1
  234. package/dist/rules/types.d.ts +0 -52
  235. package/dist/rules/types.d.ts.map +0 -1
  236. package/dist/rules/types.js +0 -2
  237. package/dist/rules/types.js.map +0 -1
  238. package/dist/rules/valid-describe-refs.d.ts +0 -7
  239. package/dist/rules/valid-describe-refs.d.ts.map +0 -1
  240. package/dist/rules/valid-describe-refs.js +0 -51
  241. package/dist/rules/valid-describe-refs.js.map +0 -1
  242. package/dist/rules/valid-detour-refs.d.ts +0 -6
  243. package/dist/rules/valid-detour-refs.d.ts.map +0 -1
  244. package/dist/rules/valid-detour-refs.js +0 -116
  245. package/dist/rules/valid-detour-refs.js.map +0 -1
  246. package/src/__tests__/cli.test.ts +0 -198
  247. package/src/__tests__/drift.test.ts +0 -74
  248. package/src/__tests__/formatters.test.ts +0 -157
  249. package/src/__tests__/implementation-returns-result.test.ts +0 -128
  250. package/src/__tests__/no-direct-implementation-call.test.ts +0 -83
  251. package/src/__tests__/no-sync-result-assumption.test.ts +0 -85
  252. package/src/__tests__/no-throw-in-detour-target.test.ts +0 -78
  253. package/src/__tests__/prefer-schema-inference.test.ts +0 -84
  254. package/src/__tests__/rules.test.ts +0 -215
  255. package/src/__tests__/valid-describe-refs.test.ts +0 -60
  256. package/src/rules/no-direct-impl-in-route.ts +0 -77
  257. package/src/rules/no-throw-in-detour-target.ts +0 -150
  258. package/src/rules/valid-detour-refs.ts +0 -187
  259. package/tsconfig.json +0 -9
  260. package/tsconfig.tsbuildinfo +0 -1
@@ -0,0 +1,214 @@
1
+ /**
2
+ * Factory that wraps a WardenRule as a trail.
3
+ *
4
+ * Keeps each rule trail file minimal — just the import + examples.
5
+ */
6
+
7
+ import { InternalError, trail, Result } from '@ontrails/core';
8
+ import type { Trail } from '@ontrails/core';
9
+
10
+ import type {
11
+ ProjectAwareWardenRule,
12
+ ProjectContext,
13
+ TopoAwareWardenRule,
14
+ WardenRule,
15
+ } from '../rules/types.js';
16
+ import { getWardenRuleMetadata } from '../rules/metadata.js';
17
+ import {
18
+ projectAwareRuleInput,
19
+ ruleInput,
20
+ ruleOutput,
21
+ topoAwareRuleInput,
22
+ } from './schema.js';
23
+ import type {
24
+ ProjectAwareRuleInput,
25
+ RuleInput,
26
+ RuleOutput,
27
+ TopoAwareRuleInput,
28
+ } from './schema.js';
29
+
30
+ interface WrapRuleOptions {
31
+ /** The existing warden rule to wrap. */
32
+ readonly rule: WardenRule;
33
+ /** Trail examples for testing and documentation. */
34
+ readonly examples: Trail<RuleInput, RuleOutput>['examples'];
35
+ }
36
+
37
+ interface WrapProjectAwareRuleOptions {
38
+ /** The existing project-aware warden rule to wrap. */
39
+ readonly rule: ProjectAwareWardenRule;
40
+ /** Trail examples for testing and documentation. */
41
+ readonly examples: Trail<ProjectAwareRuleInput, RuleOutput>['examples'];
42
+ }
43
+
44
+ const buildRuleMeta = (rule: WardenRule | TopoAwareWardenRule) => {
45
+ const metadata = getWardenRuleMetadata(rule);
46
+ return {
47
+ category: 'governance',
48
+ ...(metadata ? { warden: metadata } : {}),
49
+ severity: rule.severity,
50
+ };
51
+ };
52
+
53
+ const buildProjectContext = (input: ProjectAwareRuleInput): ProjectContext => ({
54
+ ...(input.contourReferencesByName
55
+ ? {
56
+ contourReferencesByName: new Map(
57
+ Object.entries(input.contourReferencesByName)
58
+ ),
59
+ }
60
+ : {}),
61
+ ...(input.crudTableIds ? { crudTableIds: new Set(input.crudTableIds) } : {}),
62
+ ...(input.crudCoverageByEntity
63
+ ? {
64
+ crudCoverageByEntity: new Map(
65
+ Object.entries(input.crudCoverageByEntity).map(
66
+ ([entityId, operations]) => [
67
+ entityId,
68
+ new Set(operations) as ReadonlySet<string>,
69
+ ]
70
+ )
71
+ ),
72
+ }
73
+ : {}),
74
+ ...(input.knownContourIds
75
+ ? { knownContourIds: new Set(input.knownContourIds) }
76
+ : {}),
77
+ ...(input.importResolutionsByFile
78
+ ? {
79
+ importResolutionsByFile: new Map(
80
+ Object.entries(input.importResolutionsByFile)
81
+ ),
82
+ }
83
+ : {}),
84
+ ...(input.documentedImportResolutionsByFile
85
+ ? {
86
+ documentedImportResolutionsByFile: new Map(
87
+ Object.entries(input.documentedImportResolutionsByFile)
88
+ ),
89
+ }
90
+ : {}),
91
+ ...(input.publicWorkspaces
92
+ ? { publicWorkspaces: new Map(Object.entries(input.publicWorkspaces)) }
93
+ : {}),
94
+ knownTrailIds: input.knownTrailIds
95
+ ? new Set(input.knownTrailIds)
96
+ : new Set<string>(),
97
+ ...(input.composeTargetTrailIds
98
+ ? { composeTargetTrailIds: new Set(input.composeTargetTrailIds) }
99
+ : {}),
100
+ ...(input.knownResourceIds
101
+ ? { knownResourceIds: new Set(input.knownResourceIds) }
102
+ : {}),
103
+ ...(input.knownSignalIds
104
+ ? { knownSignalIds: new Set(input.knownSignalIds) }
105
+ : {}),
106
+ ...(input.onTargetSignalIds
107
+ ? { onTargetSignalIds: new Set(input.onTargetSignalIds) }
108
+ : {}),
109
+ ...(input.reconcileTableIds
110
+ ? { reconcileTableIds: new Set(input.reconcileTableIds) }
111
+ : {}),
112
+ ...(input.trailIntentsById
113
+ ? { trailIntentsById: new Map(Object.entries(input.trailIntentsById)) }
114
+ : {}),
115
+ ...(input.topoTrailIds ? { topoTrailIds: new Set(input.topoTrailIds) } : {}),
116
+ });
117
+
118
+ /**
119
+ * Wrap an existing `WardenRule` as a trail with typed input/output.
120
+ *
121
+ * The trail ID follows the pattern `warden.rule.<rule-name>`.
122
+ */
123
+ export function wrapRule(
124
+ options: WrapProjectAwareRuleOptions
125
+ ): Trail<ProjectAwareRuleInput, RuleOutput>;
126
+ export function wrapRule(
127
+ options: WrapRuleOptions
128
+ ): Trail<RuleInput, RuleOutput>;
129
+ export function wrapRule(
130
+ options: WrapRuleOptions | WrapProjectAwareRuleOptions
131
+ ): Trail<RuleInput, RuleOutput> | Trail<ProjectAwareRuleInput, RuleOutput> {
132
+ const { rule, examples } = options;
133
+ const isProjectAware = 'checkWithContext' in rule;
134
+
135
+ if (isProjectAware) {
136
+ const projectAwareRule = rule as ProjectAwareWardenRule;
137
+ return trail(`warden.rule.${rule.name}`, {
138
+ blaze: (input: ProjectAwareRuleInput) => {
139
+ const diagnostics = projectAwareRule.checkWithContext(
140
+ input.sourceCode,
141
+ input.filePath,
142
+ buildProjectContext(input)
143
+ );
144
+ return Result.ok({ diagnostics: [...diagnostics] });
145
+ },
146
+ description: rule.description,
147
+ examples: examples as Trail<
148
+ ProjectAwareRuleInput,
149
+ RuleOutput
150
+ >['examples'],
151
+ input: projectAwareRuleInput,
152
+ intent: 'read',
153
+ meta: buildRuleMeta(rule),
154
+ output: ruleOutput,
155
+ });
156
+ }
157
+
158
+ return trail(`warden.rule.${rule.name}`, {
159
+ blaze: (input: RuleInput) => {
160
+ const diagnostics = rule.check(input.sourceCode, input.filePath);
161
+ return Result.ok({ diagnostics: [...diagnostics] });
162
+ },
163
+ description: rule.description,
164
+ examples: examples as Trail<RuleInput, RuleOutput>['examples'],
165
+ input: ruleInput,
166
+ intent: 'read',
167
+ meta: buildRuleMeta(rule),
168
+ output: ruleOutput,
169
+ });
170
+ }
171
+
172
+ interface WrapTopoRuleOptions {
173
+ /** The existing topo-aware warden rule to wrap. */
174
+ readonly rule: TopoAwareWardenRule;
175
+ /** Trail examples for testing and documentation. */
176
+ readonly examples: Trail<TopoAwareRuleInput, RuleOutput>['examples'];
177
+ }
178
+
179
+ /**
180
+ * Wrap an existing `TopoAwareWardenRule` as a trail.
181
+ *
182
+ * Mirrors `wrapRule` for the per-topo dispatch path. Topo-aware rules run
183
+ * once per topo against the compiled runtime graph rather than per file,
184
+ * so the trail accepts the live `Topo` as input.
185
+ */
186
+ export const wrapTopoRule = (
187
+ options: WrapTopoRuleOptions
188
+ ): Trail<TopoAwareRuleInput, RuleOutput> => {
189
+ const { rule, examples } = options;
190
+ return trail(`warden.rule.${rule.name}`, {
191
+ blaze: async (input: TopoAwareRuleInput) => {
192
+ try {
193
+ const diagnostics = await rule.checkTopo(input.topo, {
194
+ graph: input.graph,
195
+ });
196
+ return Result.ok({ diagnostics: [...diagnostics] });
197
+ } catch (error) {
198
+ const cause = error instanceof Error ? error : new Error(String(error));
199
+ return Result.err(
200
+ new InternalError(
201
+ `Topo-aware rule "${rule.name}" threw while inspecting topo: ${cause.message}`,
202
+ { cause }
203
+ )
204
+ );
205
+ }
206
+ },
207
+ description: rule.description,
208
+ examples,
209
+ input: topoAwareRuleInput,
210
+ intent: 'read',
211
+ meta: buildRuleMeta(rule),
212
+ output: ruleOutput,
213
+ });
214
+ };
@@ -0,0 +1,199 @@
1
+ /**
2
+ * Workspace-manifest discovery for Warden project-aware rules.
3
+ */
4
+
5
+ import { realpathSync } from 'node:fs';
6
+ import { dirname, join, relative, resolve } from 'node:path';
7
+
8
+ import { listWorkspacePackages, matchesAnyPathGlob } from '@ontrails/core';
9
+
10
+ export interface WardenPublicWorkspace {
11
+ readonly name: string;
12
+ readonly rootDir: string;
13
+ readonly packageJsonPath: string;
14
+ readonly hasExports: boolean;
15
+ readonly bin?: Readonly<Record<string, string>> | undefined;
16
+ readonly exportTargets?: Readonly<Record<string, string>> | undefined;
17
+ readonly files?: readonly string[] | undefined;
18
+ }
19
+
20
+ export interface WardenWorkspaceCollectionOptions {
21
+ readonly exclude?: readonly string[];
22
+ }
23
+
24
+ interface PackageManifest {
25
+ readonly bin?: unknown;
26
+ readonly exports?: unknown;
27
+ readonly files?: unknown;
28
+ readonly name?: unknown;
29
+ readonly private?: unknown;
30
+ }
31
+
32
+ const normalizePath = (path: string): string => path.replaceAll('\\', '/');
33
+
34
+ const normalizeRealPath = (path: string): string => {
35
+ try {
36
+ return normalizePath(realpathSync(path));
37
+ } catch {
38
+ return normalizePath(resolve(path));
39
+ }
40
+ };
41
+
42
+ const rootRelativePath = (rootDir: string, path: string): string =>
43
+ normalizePath(relative(rootDir, path));
44
+
45
+ const isRecord = (value: unknown): value is Record<string, unknown> =>
46
+ Boolean(value && typeof value === 'object' && !Array.isArray(value));
47
+
48
+ const packageLocalName = (name: string): string =>
49
+ name.split('/').at(-1) ?? name;
50
+
51
+ const normalizeBin = (
52
+ name: string,
53
+ value: unknown
54
+ ): Readonly<Record<string, string>> | undefined => {
55
+ if (typeof value === 'string') {
56
+ return { [packageLocalName(name)]: value };
57
+ }
58
+ if (!isRecord(value)) {
59
+ return undefined;
60
+ }
61
+
62
+ const entries = Object.entries(value).filter(
63
+ (entry): entry is [string, string] => typeof entry[1] === 'string'
64
+ );
65
+ return entries.length > 0 ? Object.fromEntries(entries) : undefined;
66
+ };
67
+
68
+ const normalizeFiles = (value: unknown): readonly string[] | undefined => {
69
+ if (!Array.isArray(value)) {
70
+ return undefined;
71
+ }
72
+
73
+ const files = value.filter(
74
+ (entry): entry is string => typeof entry === 'string'
75
+ );
76
+ return files.length > 0 ? files : undefined;
77
+ };
78
+
79
+ const resolveExportTarget = (
80
+ target: unknown,
81
+ depth = 0
82
+ ): string | undefined => {
83
+ if (typeof target === 'string') {
84
+ return target;
85
+ }
86
+ if (!isRecord(target) || depth > 8) {
87
+ return undefined;
88
+ }
89
+
90
+ for (const condition of ['bun', 'import', 'default', 'require'] as const) {
91
+ const conditionalTarget = target[condition];
92
+ const resolvedTarget = resolveExportTarget(conditionalTarget, depth + 1);
93
+ if (resolvedTarget) {
94
+ return resolvedTarget;
95
+ }
96
+ }
97
+ return undefined;
98
+ };
99
+
100
+ const exportSpecifierFromKey = (
101
+ packageName: string,
102
+ key: string
103
+ ): string | undefined => {
104
+ if (key === '.') {
105
+ return packageName;
106
+ }
107
+ if (!key.startsWith('./') || key.includes('*')) {
108
+ return undefined;
109
+ }
110
+ return `${packageName}/${key.slice(2)}`;
111
+ };
112
+
113
+ const normalizeExportTargets = (
114
+ packageDir: string,
115
+ packageName: string,
116
+ exportsValue: unknown
117
+ ): Readonly<Record<string, string>> | undefined => {
118
+ if (!isRecord(exportsValue)) {
119
+ return undefined;
120
+ }
121
+
122
+ const targets: Record<string, string> = {};
123
+ for (const [key, value] of Object.entries(exportsValue)) {
124
+ const specifier = exportSpecifierFromKey(packageName, key);
125
+ const target = resolveExportTarget(value);
126
+ if (!specifier || !target) {
127
+ continue;
128
+ }
129
+ targets[specifier] = normalizeRealPath(join(packageDir, target));
130
+ }
131
+
132
+ return Object.keys(targets).length > 0 ? targets : undefined;
133
+ };
134
+
135
+ const publicWorkspaceFromManifest = (
136
+ packageJsonPath: string,
137
+ manifest: PackageManifest
138
+ ): WardenPublicWorkspace | undefined => {
139
+ if (typeof manifest.name !== 'string') {
140
+ return undefined;
141
+ }
142
+ if (!manifest.name.startsWith('@ontrails/')) {
143
+ return undefined;
144
+ }
145
+ if (manifest.private === true) {
146
+ return undefined;
147
+ }
148
+
149
+ const packageDir = dirname(packageJsonPath);
150
+ const bin = normalizeBin(manifest.name, manifest.bin);
151
+ const exportTargets = normalizeExportTargets(
152
+ packageDir,
153
+ manifest.name,
154
+ manifest.exports
155
+ );
156
+ const files = normalizeFiles(manifest.files);
157
+
158
+ return {
159
+ ...(bin ? { bin } : {}),
160
+ ...(exportTargets ? { exportTargets } : {}),
161
+ ...(files ? { files } : {}),
162
+ hasExports: manifest.exports !== undefined,
163
+ name: manifest.name,
164
+ packageJsonPath: normalizeRealPath(packageJsonPath),
165
+ rootDir: normalizeRealPath(dirname(packageJsonPath)),
166
+ };
167
+ };
168
+
169
+ export const collectPublicWorkspaces = (
170
+ rootDir: string,
171
+ options: WardenWorkspaceCollectionOptions = {}
172
+ ): ReadonlyMap<string, WardenPublicWorkspace> => {
173
+ const normalizedRoot = normalizeRealPath(rootDir);
174
+ const workspaces = new Map<string, WardenPublicWorkspace>();
175
+
176
+ for (const workspacePackage of listWorkspacePackages<PackageManifest>(
177
+ normalizedRoot
178
+ )) {
179
+ const workspace = publicWorkspaceFromManifest(
180
+ workspacePackage.packageJsonPath,
181
+ workspacePackage.manifest
182
+ );
183
+ if (
184
+ workspace &&
185
+ !matchesAnyPathGlob(
186
+ rootRelativePath(normalizedRoot, workspace.rootDir),
187
+ options.exclude ?? []
188
+ ) &&
189
+ !matchesAnyPathGlob(
190
+ rootRelativePath(normalizedRoot, workspace.packageJsonPath),
191
+ options.exclude ?? []
192
+ )
193
+ ) {
194
+ workspaces.set(workspace.name, workspace);
195
+ }
196
+ }
197
+
198
+ return workspaces;
199
+ };
@@ -1 +0,0 @@
1
- $ tsc -b
@@ -1,3 +0,0 @@
1
- $ oxlint ./src
2
- Found 0 warnings and 0 errors.
3
- Finished in 46ms on 30 files with 93 rules using 24 threads.
@@ -1 +0,0 @@
1
- $ tsc --noEmit
package/dist/cli.d.ts DELETED
@@ -1,46 +0,0 @@
1
- /**
2
- * Warden CLI command runner.
3
- *
4
- * Scans TypeScript files, runs all warden rules, optionally checks drift,
5
- * and returns a structured report.
6
- */
7
- import type { Topo } from '@ontrails/core';
8
- import type { DriftResult } from './drift.js';
9
- import type { WardenDiagnostic } from './rules/types.js';
10
- /**
11
- * Options for the warden CLI runner.
12
- */
13
- export interface WardenOptions {
14
- /** Root directory to scan for TypeScript files. Defaults to cwd. */
15
- readonly rootDir?: string | undefined;
16
- /** Only run lint rules, skip drift detection */
17
- readonly lintOnly?: boolean | undefined;
18
- /** Only run drift detection, skip lint rules */
19
- readonly driftOnly?: boolean | undefined;
20
- /** App topology for drift detection. When provided, enables real surface lock comparison. */
21
- readonly topo?: Topo | undefined;
22
- }
23
- /**
24
- * Result of a warden run.
25
- */
26
- export interface WardenReport {
27
- /** All diagnostics from lint rules */
28
- readonly diagnostics: readonly WardenDiagnostic[];
29
- /** Count of error-severity diagnostics */
30
- readonly errorCount: number;
31
- /** Count of warn-severity diagnostics */
32
- readonly warnCount: number;
33
- /** Drift detection result, or null if skipped */
34
- readonly drift: DriftResult | null;
35
- /** Whether the warden run passed (no errors, no drift) */
36
- readonly passed: boolean;
37
- }
38
- /**
39
- * Run all warden checks and return a structured report.
40
- */
41
- export declare const runWarden: (options?: WardenOptions) => Promise<WardenReport>;
42
- /**
43
- * Format a warden report as a human-readable string.
44
- */
45
- export declare const formatWardenReport: (report: WardenReport) => string;
46
- //# sourceMappingURL=cli.d.ts.map
package/dist/cli.d.ts.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAS9C,OAAO,KAAK,EAGV,gBAAgB,EAEjB,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD,0CAA0C;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAyLD;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,UAAS,aAAkB,KAC1B,OAAO,CAAC,YAAY,CAqBtB,CAAC;AAsDF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,YAAY,KAAG,MAmBzD,CAAC"}
package/dist/cli.js DELETED
@@ -1,221 +0,0 @@
1
- /**
2
- * Warden CLI command runner.
3
- *
4
- * Scans TypeScript files, runs all warden rules, optionally checks drift,
5
- * and returns a structured report.
6
- */
7
- import { resolve } from 'node:path';
8
- import { checkDrift } from './drift.js';
9
- import { findConfigProperty, findTrailDefinitions, parse, walk, } from './rules/ast.js';
10
- import { wardenRules } from './rules/index.js';
11
- /**
12
- * Collect all .ts files under a directory, excluding node_modules, dist, and .git.
13
- */
14
- const isSourceFile = (match) => !match.endsWith('.d.ts') &&
15
- !match.startsWith('node_modules/') &&
16
- !match.startsWith('dist/') &&
17
- !match.startsWith('.git/') &&
18
- !match.includes('__tests__/') &&
19
- !match.includes('__test__/') &&
20
- !match.endsWith('.test.ts') &&
21
- !match.endsWith('.spec.ts');
22
- const collectTsFiles = (dir) => {
23
- const glob = new Bun.Glob('**/*.ts');
24
- let matches;
25
- try {
26
- matches = glob.scanSync({ cwd: dir, dot: false, onlyFiles: true });
27
- }
28
- catch {
29
- return [];
30
- }
31
- const files = [];
32
- for (const match of matches) {
33
- if (isSourceFile(match)) {
34
- files.push(`${dir}/${match}`);
35
- }
36
- }
37
- return files;
38
- };
39
- const collectKnownTrailIds = (sourceCode, filePath, knownTrailIds) => {
40
- const ast = parse(filePath, sourceCode);
41
- if (!ast) {
42
- return;
43
- }
44
- for (const def of findTrailDefinitions(ast)) {
45
- knownTrailIds.add(def.id);
46
- }
47
- };
48
- const collectDetourTargetTrailIds = (sourceCode, filePath, detourTargetTrailIds) => {
49
- const ast = parse(filePath, sourceCode);
50
- if (!ast) {
51
- return;
52
- }
53
- for (const def of findTrailDefinitions(ast)) {
54
- const detoursProp = findConfigProperty(def.config, 'detours');
55
- if (!detoursProp) {
56
- continue;
57
- }
58
- // Walk the detours value for string literals that look like trail IDs
59
- walk(detoursProp, (node) => {
60
- if (node.type !== 'Literal') {
61
- return;
62
- }
63
- const val = node.value;
64
- if (val && val.includes('.')) {
65
- detourTargetTrailIds.add(val);
66
- }
67
- });
68
- }
69
- };
70
- const loadSourceFiles = async (rootDir) => {
71
- const sourceFiles = [];
72
- for (const filePath of collectTsFiles(rootDir)) {
73
- try {
74
- sourceFiles.push({
75
- filePath,
76
- sourceCode: await Bun.file(filePath).text(),
77
- });
78
- }
79
- catch {
80
- continue;
81
- }
82
- }
83
- return sourceFiles;
84
- };
85
- const buildProjectContextFromTopo = (appTopo) => {
86
- const knownTrailIds = new Set([
87
- ...appTopo.trails.keys(),
88
- ...appTopo.hikes.keys(),
89
- ]);
90
- const detourTargetTrailIds = new Set();
91
- for (const t of [...appTopo.trails.values(), ...appTopo.hikes.values()]) {
92
- const detours = t['detours'];
93
- if (!detours) {
94
- continue;
95
- }
96
- for (const targets of Object.values(detours)) {
97
- for (const id of targets) {
98
- detourTargetTrailIds.add(id);
99
- }
100
- }
101
- }
102
- return { detourTargetTrailIds, knownTrailIds };
103
- };
104
- const buildProjectContextFromFiles = (sourceFiles) => {
105
- const knownTrailIds = new Set();
106
- const detourTargetTrailIds = new Set();
107
- for (const sourceFile of sourceFiles) {
108
- collectKnownTrailIds(sourceFile.sourceCode, sourceFile.filePath, knownTrailIds);
109
- collectDetourTargetTrailIds(sourceFile.sourceCode, sourceFile.filePath, detourTargetTrailIds);
110
- }
111
- return {
112
- detourTargetTrailIds,
113
- knownTrailIds,
114
- };
115
- };
116
- const isProjectAwareRule = (rule) => 'checkWithContext' in rule;
117
- /**
118
- * Lint all files against all warden rules.
119
- */
120
- const lintFiles = async (rootDir, appTopo) => {
121
- const allDiagnostics = [];
122
- const sourceFiles = await loadSourceFiles(rootDir);
123
- const context = appTopo
124
- ? buildProjectContextFromTopo(appTopo)
125
- : buildProjectContextFromFiles(sourceFiles);
126
- for (const sourceFile of sourceFiles) {
127
- for (const rule of wardenRules.values()) {
128
- if (isProjectAwareRule(rule)) {
129
- allDiagnostics.push(...rule.checkWithContext(sourceFile.sourceCode, sourceFile.filePath, context));
130
- continue;
131
- }
132
- allDiagnostics.push(...rule.check(sourceFile.sourceCode, sourceFile.filePath));
133
- }
134
- }
135
- return allDiagnostics;
136
- };
137
- /**
138
- * Run all warden checks and return a structured report.
139
- */
140
- export const runWarden = async (options = {}) => {
141
- const rootDir = resolve(options.rootDir ?? process.cwd());
142
- const allDiagnostics = options.driftOnly
143
- ? []
144
- : await lintFiles(rootDir, options.topo);
145
- const drift = options.lintOnly
146
- ? null
147
- : await checkDrift(rootDir, options.topo);
148
- const errorCount = allDiagnostics.filter((d) => d.severity === 'error').length;
149
- const warnCount = allDiagnostics.filter((d) => d.severity === 'warn').length;
150
- return {
151
- diagnostics: allDiagnostics,
152
- drift,
153
- errorCount,
154
- passed: errorCount === 0 && !(drift?.stale ?? false),
155
- warnCount,
156
- };
157
- };
158
- /**
159
- * Format the lint section of the report.
160
- */
161
- const formatLintSection = (report) => {
162
- if (report.diagnostics.length === 0) {
163
- return ['Lint: clean'];
164
- }
165
- const lines = [
166
- `Lint: ${report.errorCount} errors, ${report.warnCount} warnings`,
167
- ];
168
- for (const d of report.diagnostics) {
169
- const prefix = d.severity === 'error' ? 'ERROR' : 'WARN';
170
- lines.push(` ${d.filePath}:${String(d.line)} [${prefix}] ${d.rule} ${d.message}`);
171
- }
172
- return lines;
173
- };
174
- /**
175
- * Format the drift section of the report.
176
- */
177
- const formatDriftSection = (drift) => {
178
- if (drift === null) {
179
- return [];
180
- }
181
- const label = drift.stale
182
- ? 'Drift: surface.lock is stale (regenerate with `trails survey generate`)'
183
- : 'Drift: clean';
184
- return [label, ''];
185
- };
186
- /**
187
- * Format the result line.
188
- */
189
- const formatResultLine = (report) => {
190
- if (report.passed) {
191
- return 'Result: PASS';
192
- }
193
- const parts = [];
194
- if (report.errorCount > 0) {
195
- parts.push(`${report.errorCount} errors`);
196
- }
197
- if (report.drift?.stale) {
198
- parts.push('drift detected');
199
- }
200
- return `Result: FAIL (${parts.join(', ')})`;
201
- };
202
- /**
203
- * Format a warden report as a human-readable string.
204
- */
205
- export const formatWardenReport = (report) => {
206
- const lintLines = formatLintSection(report);
207
- const driftLines = formatDriftSection(report.drift);
208
- if (lintLines.length === 0 && driftLines.length === 0) {
209
- return ['Warden Report', '=============', '', 'No checks were run.'].join('\n');
210
- }
211
- return [
212
- 'Warden Report',
213
- '=============',
214
- '',
215
- ...lintLines,
216
- '',
217
- ...driftLines,
218
- formatResultLine(report),
219
- ].join('\n');
220
- };
221
- //# sourceMappingURL=cli.js.map