@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.41

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 (279) hide show
  1. package/CHANGELOG.md +835 -13
  2. package/README.md +133 -26
  3. package/bin/warden.ts +51 -0
  4. package/package.json +27 -6
  5. package/src/adapter-check.ts +136 -0
  6. package/src/cli.ts +1570 -105
  7. package/src/command.ts +986 -0
  8. package/src/config.ts +193 -0
  9. package/src/draft.ts +22 -0
  10. package/src/drift.ts +233 -23
  11. package/src/fix.ts +126 -0
  12. package/src/formatters.ts +78 -13
  13. package/src/guide.ts +245 -0
  14. package/src/index.ts +247 -15
  15. package/src/project-context.ts +446 -0
  16. package/src/project-rules.ts +290 -0
  17. package/src/resolve.ts +531 -0
  18. package/src/rules/activation-orphan.ts +97 -0
  19. package/src/rules/captured-kernel.ts +375 -0
  20. package/src/rules/circular-refs.ts +150 -0
  21. package/src/rules/cli-command-route-coherence.ts +177 -0
  22. package/src/rules/composes-declarations.ts +839 -0
  23. package/src/rules/context-no-surface-types.ts +79 -15
  24. package/src/rules/dead-internal-trail.ts +161 -0
  25. package/src/rules/dead-public-trail.ts +258 -0
  26. package/src/rules/draft-file-marking.ts +155 -0
  27. package/src/rules/draft-visible-debt.ts +82 -0
  28. package/src/rules/duplicate-exported-symbol.ts +211 -0
  29. package/src/rules/duplicate-public-contract.ts +137 -0
  30. package/src/rules/entity-exists.ts +254 -0
  31. package/src/rules/entity-ids.ts +15 -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 +740 -0
  35. package/src/rules/governed-symbol-residue.ts +438 -0
  36. package/src/rules/implementation-returns-result.ts +1409 -166
  37. package/src/rules/incomplete-accessor-for-standard-op.ts +272 -0
  38. package/src/rules/incomplete-crud.ts +583 -0
  39. package/src/rules/index.ts +277 -10
  40. package/src/rules/intent-propagation.ts +125 -0
  41. package/src/rules/layer-field-name-drift.ts +102 -0
  42. package/src/rules/library-projection-coherence.ts +100 -0
  43. package/src/rules/metadata.ts +871 -0
  44. package/src/rules/missing-reconcile.ts +97 -0
  45. package/src/rules/missing-visibility.ts +111 -0
  46. package/src/rules/no-destructured-compose.ts +196 -0
  47. package/src/rules/no-dev-permit-in-source.ts +99 -0
  48. package/src/rules/no-direct-implementation-call.ts +12 -7
  49. package/src/rules/no-legacy-cli-alias-export.ts +247 -0
  50. package/src/rules/no-legacy-layer-imports.ts +211 -0
  51. package/src/rules/no-native-error-result.ts +118 -0
  52. package/src/rules/no-redundant-result-error-wrap.ts +384 -0
  53. package/src/rules/no-retired-cross-vocabulary.ts +204 -0
  54. package/src/rules/no-sync-result-assumption.ts +1141 -98
  55. package/src/rules/no-throw-in-detour-recover.ts +225 -0
  56. package/src/rules/no-throw-in-implementation.ts +15 -8
  57. package/src/rules/no-top-level-surface.ts +371 -0
  58. package/src/rules/on-references-exist.ts +194 -0
  59. package/src/rules/orphaned-signal.ts +149 -0
  60. package/src/rules/owner-projection-parity.ts +143 -0
  61. package/src/rules/permit-governance.ts +25 -0
  62. package/src/rules/public-export-example-coverage.ts +573 -0
  63. package/src/rules/public-internal-deep-imports.ts +456 -0
  64. package/src/rules/public-output-schema.ts +29 -0
  65. package/src/rules/public-union-output-discriminants.ts +150 -0
  66. package/src/rules/read-intent-fires.ts +188 -0
  67. package/src/rules/reference-exists.ts +97 -0
  68. package/src/rules/registry-names.ts +167 -0
  69. package/src/rules/resolved-import-boundary.ts +146 -0
  70. package/src/rules/resource-declarations.ts +697 -0
  71. package/src/rules/resource-exists.ts +181 -0
  72. package/src/rules/resource-id-grammar.ts +65 -0
  73. package/src/rules/resource-mock-coverage.ts +115 -0
  74. package/src/rules/retired-vocabulary.ts +633 -0
  75. package/src/rules/scan.ts +38 -25
  76. package/src/rules/scheduled-destroy-intent.ts +44 -0
  77. package/src/rules/signal-graph-coaching.ts +220 -0
  78. package/src/rules/source/composition.ts +165 -0
  79. package/src/rules/source/drafts.ts +164 -0
  80. package/src/rules/source/entities.ts +618 -0
  81. package/src/rules/source/pragmas.ts +45 -0
  82. package/src/rules/source/resources.ts +64 -0
  83. package/src/rules/source/signals.ts +397 -0
  84. package/src/rules/source/stores.ts +310 -0
  85. package/src/rules/specs.ts +9 -5
  86. package/src/rules/static-resource-accessor-preference.ts +653 -0
  87. package/src/rules/surface-overlay-coherence.ts +262 -0
  88. package/src/rules/surface-trailhead-coherence.ts +366 -0
  89. package/src/rules/trail-fork-coaching.ts +625 -0
  90. package/src/rules/trail-versioning-source.ts +1076 -0
  91. package/src/rules/trail-versioning-topo.ts +172 -0
  92. package/src/rules/trailhead-override-divergence.ts +356 -0
  93. package/src/rules/types.ts +354 -8
  94. package/src/rules/unmaterialized-activation-source.ts +85 -0
  95. package/src/rules/unreachable-detour-shadowing.ts +339 -0
  96. package/src/rules/valid-describe-refs.ts +162 -32
  97. package/src/rules/valid-detour-contract.ts +78 -0
  98. package/src/rules/warden-export-symmetry.ts +540 -0
  99. package/src/rules/warden-rules-use-ast.ts +1109 -0
  100. package/src/rules/webhook-route-collision.ts +306 -0
  101. package/src/trails/activation-orphan.trail.ts +84 -0
  102. package/src/trails/captured-kernel.trail.ts +108 -0
  103. package/src/trails/circular-refs.trail.ts +29 -0
  104. package/src/trails/cli-command-route-coherence.trail.ts +47 -0
  105. package/src/trails/composes-declarations.trail.ts +22 -0
  106. package/src/trails/context-no-surface-types.trail.ts +21 -0
  107. package/src/trails/dead-internal-trail.trail.ts +26 -0
  108. package/src/trails/dead-public-trail.trail.ts +31 -0
  109. package/src/trails/deprecation-without-guidance.trail.ts +21 -0
  110. package/src/trails/draft-file-marking.trail.ts +16 -0
  111. package/src/trails/draft-visible-debt.trail.ts +16 -0
  112. package/src/trails/duplicate-exported-symbol.trail.ts +48 -0
  113. package/src/trails/duplicate-public-contract.trail.ts +47 -0
  114. package/src/trails/entity-exists.trail.ts +21 -0
  115. package/src/trails/error-mapping-completeness.trail.ts +30 -0
  116. package/src/trails/example-valid.trail.ts +25 -0
  117. package/src/trails/fires-declarations.trail.ts +23 -0
  118. package/src/trails/fork-without-preserved-implementation.trail.ts +31 -0
  119. package/src/trails/governed-symbol-residue.trail.ts +24 -0
  120. package/src/trails/implementation-returns-result.trail.ts +20 -0
  121. package/src/trails/incomplete-accessor-for-standard-op.trail.ts +76 -0
  122. package/src/trails/incomplete-crud.trail.ts +39 -0
  123. package/src/trails/index.ts +89 -0
  124. package/src/trails/intent-propagation.trail.ts +30 -0
  125. package/src/trails/layer-field-name-drift.trail.ts +39 -0
  126. package/src/trails/library-projection-coherence.trail.ts +43 -0
  127. package/src/trails/marker-schema-unsupported.trail.ts +23 -0
  128. package/src/trails/missing-reconcile.trail.ts +33 -0
  129. package/src/trails/missing-visibility.trail.ts +22 -0
  130. package/src/trails/no-destructured-compose.trail.ts +44 -0
  131. package/src/trails/no-dev-permit-in-source.trail.ts +16 -0
  132. package/src/trails/no-direct-implementation-call.trail.ts +16 -0
  133. package/src/trails/no-legacy-cli-alias-export.trail.ts +41 -0
  134. package/src/trails/no-legacy-layer-imports.trail.ts +41 -0
  135. package/src/trails/no-native-error-result.trail.ts +18 -0
  136. package/src/trails/no-redundant-result-error-wrap.trail.ts +55 -0
  137. package/src/trails/no-retired-cross-vocabulary.trail.ts +42 -0
  138. package/src/trails/no-sync-result-assumption.trail.ts +19 -0
  139. package/src/trails/no-throw-in-detour-recover.trail.ts +24 -0
  140. package/src/trails/no-throw-in-implementation.trail.ts +20 -0
  141. package/src/trails/no-top-level-surface.trail.ts +43 -0
  142. package/src/trails/on-references-exist.trail.ts +21 -0
  143. package/src/trails/orphaned-signal.trail.ts +36 -0
  144. package/src/trails/owner-projection-parity.trail.ts +26 -0
  145. package/src/trails/pending-force.trail.ts +21 -0
  146. package/src/trails/permit-governance.trail.ts +51 -0
  147. package/src/trails/prefer-schema-inference.trail.ts +21 -0
  148. package/src/trails/public-export-example-coverage.trail.ts +16 -0
  149. package/src/trails/public-internal-deep-imports.trail.ts +94 -0
  150. package/src/trails/public-output-schema.trail.ts +55 -0
  151. package/src/trails/public-union-output-discriminants.trail.ts +33 -0
  152. package/src/trails/read-intent-fires.trail.ts +20 -0
  153. package/src/trails/reference-exists.trail.ts +25 -0
  154. package/src/trails/resolved-import-boundary.trail.ts +109 -0
  155. package/src/trails/resource-declarations.trail.ts +25 -0
  156. package/src/trails/resource-exists.trail.ts +27 -0
  157. package/src/trails/resource-id-grammar.trail.ts +39 -0
  158. package/src/trails/resource-mock-coverage.trail.ts +40 -0
  159. package/src/trails/run.ts +160 -0
  160. package/src/trails/scheduled-destroy-intent.trail.ts +56 -0
  161. package/src/trails/schema.ts +237 -0
  162. package/src/trails/signal-graph-coaching.trail.ts +77 -0
  163. package/src/trails/static-resource-accessor-preference.trail.ts +25 -0
  164. package/src/trails/surface-overlay-coherence.trail.ts +24 -0
  165. package/src/trails/surface-trailhead-coherence.trail.ts +25 -0
  166. package/src/trails/topo.ts +6 -0
  167. package/src/trails/trail-fork-coaching.trail.ts +42 -0
  168. package/src/trails/trailhead-override-divergence.trail.ts +47 -0
  169. package/src/trails/unmaterialized-activation-source.trail.ts +72 -0
  170. package/src/trails/unreachable-detour-shadowing.trail.ts +45 -0
  171. package/src/trails/valid-describe-refs.trail.ts +18 -0
  172. package/src/trails/valid-detour-contract.trail.ts +71 -0
  173. package/src/trails/version-gap.trail.ts +35 -0
  174. package/src/trails/version-pinned-compose.trail.ts +23 -0
  175. package/src/trails/version-without-examples.trail.ts +38 -0
  176. package/src/trails/warden-export-symmetry.trail.ts +16 -0
  177. package/src/trails/warden-rules-use-ast.trail.ts +64 -0
  178. package/src/trails/webhook-route-collision.trail.ts +50 -0
  179. package/src/trails/wrap-rule.ts +224 -0
  180. package/src/workspaces.ts +199 -0
  181. package/.turbo/turbo-build.log +0 -1
  182. package/.turbo/turbo-lint.log +0 -3
  183. package/.turbo/turbo-typecheck.log +0 -1
  184. package/dist/cli.d.ts +0 -46
  185. package/dist/cli.d.ts.map +0 -1
  186. package/dist/cli.js +0 -218
  187. package/dist/cli.js.map +0 -1
  188. package/dist/drift.d.ts +0 -26
  189. package/dist/drift.d.ts.map +0 -1
  190. package/dist/drift.js +0 -27
  191. package/dist/drift.js.map +0 -1
  192. package/dist/formatters.d.ts +0 -29
  193. package/dist/formatters.d.ts.map +0 -1
  194. package/dist/formatters.js +0 -87
  195. package/dist/formatters.js.map +0 -1
  196. package/dist/index.d.ts +0 -26
  197. package/dist/index.d.ts.map +0 -1
  198. package/dist/index.js +0 -26
  199. package/dist/index.js.map +0 -1
  200. package/dist/rules/ast.d.ts +0 -41
  201. package/dist/rules/ast.d.ts.map +0 -1
  202. package/dist/rules/ast.js +0 -161
  203. package/dist/rules/ast.js.map +0 -1
  204. package/dist/rules/context-no-surface-types.d.ts +0 -12
  205. package/dist/rules/context-no-surface-types.d.ts.map +0 -1
  206. package/dist/rules/context-no-surface-types.js +0 -96
  207. package/dist/rules/context-no-surface-types.js.map +0 -1
  208. package/dist/rules/implementation-returns-result.d.ts +0 -13
  209. package/dist/rules/implementation-returns-result.d.ts.map +0 -1
  210. package/dist/rules/implementation-returns-result.js +0 -277
  211. package/dist/rules/implementation-returns-result.js.map +0 -1
  212. package/dist/rules/index.d.ts +0 -15
  213. package/dist/rules/index.d.ts.map +0 -1
  214. package/dist/rules/index.js +0 -34
  215. package/dist/rules/index.js.map +0 -1
  216. package/dist/rules/no-direct-impl-in-route.d.ts +0 -12
  217. package/dist/rules/no-direct-impl-in-route.d.ts.map +0 -1
  218. package/dist/rules/no-direct-impl-in-route.js +0 -47
  219. package/dist/rules/no-direct-impl-in-route.js.map +0 -1
  220. package/dist/rules/no-direct-implementation-call.d.ts +0 -12
  221. package/dist/rules/no-direct-implementation-call.d.ts.map +0 -1
  222. package/dist/rules/no-direct-implementation-call.js +0 -39
  223. package/dist/rules/no-direct-implementation-call.js.map +0 -1
  224. package/dist/rules/no-sync-result-assumption.d.ts +0 -6
  225. package/dist/rules/no-sync-result-assumption.d.ts.map +0 -1
  226. package/dist/rules/no-sync-result-assumption.js +0 -98
  227. package/dist/rules/no-sync-result-assumption.js.map +0 -1
  228. package/dist/rules/no-throw-in-detour-target.d.ts +0 -12
  229. package/dist/rules/no-throw-in-detour-target.d.ts.map +0 -1
  230. package/dist/rules/no-throw-in-detour-target.js +0 -87
  231. package/dist/rules/no-throw-in-detour-target.js.map +0 -1
  232. package/dist/rules/no-throw-in-implementation.d.ts +0 -9
  233. package/dist/rules/no-throw-in-implementation.d.ts.map +0 -1
  234. package/dist/rules/no-throw-in-implementation.js +0 -34
  235. package/dist/rules/no-throw-in-implementation.js.map +0 -1
  236. package/dist/rules/prefer-schema-inference.d.ts +0 -7
  237. package/dist/rules/prefer-schema-inference.d.ts.map +0 -1
  238. package/dist/rules/prefer-schema-inference.js +0 -86
  239. package/dist/rules/prefer-schema-inference.js.map +0 -1
  240. package/dist/rules/scan.d.ts +0 -8
  241. package/dist/rules/scan.d.ts.map +0 -1
  242. package/dist/rules/scan.js +0 -32
  243. package/dist/rules/scan.js.map +0 -1
  244. package/dist/rules/specs.d.ts +0 -29
  245. package/dist/rules/specs.d.ts.map +0 -1
  246. package/dist/rules/specs.js +0 -192
  247. package/dist/rules/specs.js.map +0 -1
  248. package/dist/rules/structure.d.ts +0 -13
  249. package/dist/rules/structure.d.ts.map +0 -1
  250. package/dist/rules/structure.js +0 -142
  251. package/dist/rules/structure.js.map +0 -1
  252. package/dist/rules/types.d.ts +0 -52
  253. package/dist/rules/types.d.ts.map +0 -1
  254. package/dist/rules/types.js +0 -2
  255. package/dist/rules/types.js.map +0 -1
  256. package/dist/rules/valid-describe-refs.d.ts +0 -7
  257. package/dist/rules/valid-describe-refs.d.ts.map +0 -1
  258. package/dist/rules/valid-describe-refs.js +0 -51
  259. package/dist/rules/valid-describe-refs.js.map +0 -1
  260. package/dist/rules/valid-detour-refs.d.ts +0 -6
  261. package/dist/rules/valid-detour-refs.d.ts.map +0 -1
  262. package/dist/rules/valid-detour-refs.js +0 -116
  263. package/dist/rules/valid-detour-refs.js.map +0 -1
  264. package/src/__tests__/cli.test.ts +0 -198
  265. package/src/__tests__/drift.test.ts +0 -74
  266. package/src/__tests__/formatters.test.ts +0 -157
  267. package/src/__tests__/implementation-returns-result.test.ts +0 -129
  268. package/src/__tests__/no-direct-implementation-call.test.ts +0 -83
  269. package/src/__tests__/no-sync-result-assumption.test.ts +0 -85
  270. package/src/__tests__/no-throw-in-detour-target.test.ts +0 -78
  271. package/src/__tests__/prefer-schema-inference.test.ts +0 -84
  272. package/src/__tests__/rules.test.ts +0 -227
  273. package/src/__tests__/valid-describe-refs.test.ts +0 -60
  274. package/src/rules/ast.ts +0 -213
  275. package/src/rules/no-direct-impl-in-route.ts +0 -81
  276. package/src/rules/no-throw-in-detour-target.ts +0 -150
  277. package/src/rules/valid-detour-refs.ts +0 -187
  278. package/tsconfig.json +0 -9
  279. package/tsconfig.tsbuildinfo +0 -1
@@ -0,0 +1,21 @@
1
+ import { topo } from '@ontrails/core';
2
+ import { deriveTopoGraph } from '@ontrails/topography';
3
+
4
+ import { deprecationWithoutGuidance } from '../rules/trail-versioning-topo.js';
5
+ import { wrapTopoRule } from './wrap-rule.js';
6
+
7
+ const emptyTopo = topo('deprecation-without-guidance-clean', {});
8
+
9
+ export const deprecationWithoutGuidanceTrail = wrapTopoRule({
10
+ examples: [
11
+ {
12
+ expected: { diagnostics: [] },
13
+ input: {
14
+ graph: deriveTopoGraph(emptyTopo),
15
+ topo: emptyTopo,
16
+ },
17
+ name: 'No deprecated version entries passes',
18
+ },
19
+ ],
20
+ rule: deprecationWithoutGuidance,
21
+ });
@@ -0,0 +1,16 @@
1
+ import { draftFileMarking } from '../rules/draft-file-marking.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const draftFileMarkingTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'clean.ts',
10
+ sourceCode: `export const id = "notes.list";`,
11
+ },
12
+ name: 'File without draft ids passes',
13
+ },
14
+ ],
15
+ rule: draftFileMarking,
16
+ });
@@ -0,0 +1,16 @@
1
+ import { draftVisibleDebt } from '../rules/draft-visible-debt.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const draftVisibleDebtTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'clean.ts',
10
+ sourceCode: `export const id = "notes.list";`,
11
+ },
12
+ name: 'File without draft ids emits no visible-debt diagnostics',
13
+ },
14
+ ],
15
+ rule: draftVisibleDebt,
16
+ });
@@ -0,0 +1,48 @@
1
+ import { duplicateExportedSymbol } from '../rules/duplicate-exported-symbol.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const duplicateExportedSymbolTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: {
8
+ diagnostics: [
9
+ {
10
+ filePath: '/repo/packages/core/src/index.ts',
11
+ line: 1,
12
+ message:
13
+ 'Exported symbol "createClient" is defined by @ontrails/core and also by @ontrails/store (/repo/packages/store/src/index.ts:1). Keep one package as the owner, rename one side, or document a deliberate ownership mirror before exporting both symbols.',
14
+ rule: 'duplicate-exported-symbol',
15
+ severity: 'warn',
16
+ },
17
+ ],
18
+ },
19
+ input: {
20
+ exportedSymbolDefinitionsByName: {
21
+ createClient: [
22
+ {
23
+ filePath: '/repo/packages/core/src/index.ts',
24
+ kind: 'function',
25
+ line: 1,
26
+ name: 'createClient',
27
+ workspaceName: '@ontrails/core',
28
+ workspaceRoot: '/repo/packages/core',
29
+ },
30
+ {
31
+ filePath: '/repo/packages/store/src/index.ts',
32
+ kind: 'function',
33
+ line: 1,
34
+ name: 'createClient',
35
+ workspaceName: '@ontrails/store',
36
+ workspaceRoot: '/repo/packages/store',
37
+ },
38
+ ],
39
+ },
40
+ filePath: '/repo/packages/core/src/index.ts',
41
+ knownTrailIds: [],
42
+ sourceCode: 'export function createClient() {}',
43
+ },
44
+ name: 'Flags duplicate exported symbol definitions across packages',
45
+ },
46
+ ],
47
+ rule: duplicateExportedSymbol,
48
+ });
@@ -0,0 +1,47 @@
1
+ import { Result, topo, trail } from '@ontrails/core';
2
+ import { z } from 'zod';
3
+
4
+ import { duplicatePublicContract } from '../rules/duplicate-public-contract.js';
5
+ import { wrapTopoRule } from './wrap-rule.js';
6
+
7
+ const sharedInput = z.object({ target: z.string() });
8
+ const sharedOutput = z.object({ ok: z.boolean() });
9
+
10
+ const canonicalTrail = trail('survey.diff', {
11
+ implementation: () => Result.ok({ ok: true }),
12
+ input: sharedInput,
13
+ output: sharedOutput,
14
+ });
15
+
16
+ const duplicateTrail = trail('diff', {
17
+ implementation: () => Result.ok({ ok: true }),
18
+ input: sharedInput,
19
+ output: sharedOutput,
20
+ });
21
+
22
+ export const duplicatePublicContractTrail = wrapTopoRule({
23
+ examples: [
24
+ {
25
+ expected: {
26
+ diagnostics: [
27
+ {
28
+ filePath: '<topo>',
29
+ line: 1,
30
+ message:
31
+ 'Likely duplicate public trail contracts "diff", "survey.diff" share the same input, output, intent, permits, resources, entities, composes, signals, and detours. Keep one contract with aliases/input mappings, compose a distinct wrapper, or document why these public contracts are separate.',
32
+ rule: 'duplicate-public-contract',
33
+ severity: 'warn',
34
+ },
35
+ ],
36
+ },
37
+ input: {
38
+ topo: topo('duplicate-public-contract', {
39
+ canonicalTrail,
40
+ duplicateTrail,
41
+ }),
42
+ },
43
+ name: 'Duplicate public surface contracts are coached',
44
+ },
45
+ ],
46
+ rule: duplicatePublicContract,
47
+ });
@@ -0,0 +1,21 @@
1
+ import { entityExists } from '../rules/entity-exists.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const entityExistsTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'entity.ts',
10
+ knownEntityIds: ['user'],
11
+ knownTrailIds: ['user.create'],
12
+ sourceCode: `trail("user.create", {
13
+ entities: [user],
14
+ implementation: async (input, ctx) => Result.ok({ ok: true }),
15
+ })`,
16
+ },
17
+ name: 'Declared entities resolve to known project entities',
18
+ },
19
+ ],
20
+ rule: entityExists,
21
+ });
@@ -0,0 +1,30 @@
1
+ import { errorMappingCompleteness } from '../rules/error-mapping-completeness.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const errorMappingCompletenessTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'surface-error-map.ts',
10
+ sourceCode: `import { createSurfaceErrorMapper } from "@ontrails/core";
11
+
12
+ const cliMapper = createSurfaceErrorMapper({
13
+ auth: 9,
14
+ cancelled: 130,
15
+ conflict: 3,
16
+ internal: 8,
17
+ network: 7,
18
+ not_found: 2,
19
+ permission: 4,
20
+ rate_limit: 6,
21
+ shift: 10,
22
+ timeout: 5,
23
+ validation: 1,
24
+ });`,
25
+ },
26
+ name: 'Complete surface error mapper',
27
+ },
28
+ ],
29
+ rule: errorMappingCompleteness,
30
+ });
@@ -0,0 +1,25 @@
1
+ import { exampleValid } from '../rules/example-valid.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const exampleValidTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'entities.ts',
10
+ sourceCode: `const user = entity("user", {
11
+ id: z.string().uuid(),
12
+ name: z.string(),
13
+ }, {
14
+ examples: [{
15
+ id: "550e8400-e29b-41d4-a716-446655440000",
16
+ name: "Ada",
17
+ }],
18
+ identity: "id",
19
+ });`,
20
+ },
21
+ name: 'Entity examples validate against their schema',
22
+ },
23
+ ],
24
+ rule: exampleValid,
25
+ });
@@ -0,0 +1,23 @@
1
+ import { firesDeclarations } from '../rules/fires-declarations.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const firesDeclarationsTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'clean.ts',
10
+ sourceCode: `const entityCreated = signal("entity.created", { payload: z.object({}) });
11
+ trail("entity.onboard", {
12
+ fires: [entityCreated],
13
+ implementation: async (input, ctx) => {
14
+ await ctx.fire(entityCreated, { id: input.id });
15
+ return Result.ok({});
16
+ }
17
+ })`,
18
+ },
19
+ name: 'Matched fires declarations and calls',
20
+ },
21
+ ],
22
+ rule: firesDeclarations,
23
+ });
@@ -0,0 +1,31 @@
1
+ import { forkWithoutPreservedImplementation } from '../rules/trail-versioning-source.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const forkWithoutPreservedImplementationTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'src/trails/versioned.ts',
10
+ sourceCode: `
11
+ trail('versioned.clean', {
12
+ version: 2,
13
+ versions: {
14
+ 1: {
15
+ input: z.object({ name: z.string() }),
16
+ output: z.object({ message: z.string() }),
17
+ transpose: {
18
+ input: ({ input }) => input,
19
+ output: ({ output }) => output,
20
+ },
21
+ },
22
+ },
23
+ implementation: async () => Result.ok({ message: 'ok' }),
24
+ });
25
+ `,
26
+ },
27
+ name: 'Revision entries use transpose',
28
+ },
29
+ ],
30
+ rule: forkWithoutPreservedImplementation,
31
+ });
@@ -0,0 +1,24 @@
1
+ import { governedSymbolResidue } from '../rules/governed-symbol-residue.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const governedSymbolResidueTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'packages/example/src/trails/play.ts',
10
+ sourceCode: 'const composeInput = { id: "track" };\n',
11
+ },
12
+ name: 'Current governed symbol vocabulary is clean',
13
+ },
14
+ {
15
+ expected: { diagnostics: [] },
16
+ input: {
17
+ filePath: 'packages/example/src/trails/play.ts',
18
+ sourceCode: 'const crossInput = { id: "track" };\n',
19
+ },
20
+ name: 'Cross-compose vocabulary is owned by the beta.19 rule',
21
+ },
22
+ ],
23
+ rule: governedSymbolResidue,
24
+ });
@@ -0,0 +1,20 @@
1
+ import { implementationReturnsResult } from '../rules/implementation-returns-result.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const implementationReturnsResultTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'clean.ts',
10
+ sourceCode: `trail("entity.show", {
11
+ implementation: async (input, ctx) => {
12
+ return Result.ok({ name: "test" });
13
+ }
14
+ })`,
15
+ },
16
+ name: 'Implementation returning Result.ok()',
17
+ },
18
+ ],
19
+ rule: implementationReturnsResult,
20
+ });
@@ -0,0 +1,76 @@
1
+ import { resource, Result, topo, trail } from '@ontrails/core';
2
+ import { z } from 'zod';
3
+
4
+ import { incompleteAccessorForStandardOp } from '../rules/incomplete-accessor-for-standard-op.js';
5
+ import { wrapTopoRule } from './wrap-rule.js';
6
+
7
+ type Accessor = Readonly<Record<string, (...args: unknown[]) => unknown>>;
8
+ type Connection = Readonly<Record<string, Accessor>>;
9
+
10
+ const noop = (): undefined => undefined;
11
+
12
+ const buildResource = (id: string, entityName: string, accessor: Accessor) =>
13
+ resource<Connection>(id, {
14
+ create: () => Result.ok({ [entityName]: accessor }),
15
+ mock: () => ({ [entityName]: accessor }),
16
+ });
17
+
18
+ const buildCrudTrail = (
19
+ trailId: string,
20
+ resourceValue: ReturnType<typeof buildResource>
21
+ ) =>
22
+ trail(trailId, {
23
+ implementation: () => Result.ok({ ok: true }),
24
+ input: z.object({}),
25
+ output: z.object({ ok: z.boolean() }),
26
+ pattern: 'crud',
27
+ resources: [resourceValue],
28
+ });
29
+
30
+ const cleanResource = buildResource('store.note.clean', 'note', {
31
+ insert: noop,
32
+ });
33
+ const warningResource = buildResource('store.note.warn', 'note', {
34
+ upsert: noop,
35
+ });
36
+
37
+ const cleanTopo = topo('trl-269-clean', {
38
+ noteCreate: buildCrudTrail('note.create', cleanResource),
39
+ noteResource: cleanResource,
40
+ });
41
+
42
+ const warningTopo = topo('trl-269-warning', {
43
+ noteCreate: buildCrudTrail('note.create', warningResource),
44
+ noteResource: warningResource,
45
+ });
46
+
47
+ export const incompleteAccessorForStandardOpTrail = wrapTopoRule({
48
+ examples: [
49
+ {
50
+ expected: { diagnostics: [] },
51
+ input: {
52
+ topo: cleanTopo,
53
+ },
54
+ name: 'Preferred accessors keep CRUD trails quiet',
55
+ },
56
+ {
57
+ expected: {
58
+ diagnostics: [
59
+ {
60
+ filePath: '<topo>',
61
+ line: 1,
62
+ message:
63
+ 'Trail "note.create" (crud.create): resource "store.note.warn" accessor "note" is missing preferred method "insert"; falls back to "upsert"',
64
+ rule: 'incomplete-accessor-for-standard-op',
65
+ severity: 'warn',
66
+ },
67
+ ],
68
+ },
69
+ input: {
70
+ topo: warningTopo,
71
+ },
72
+ name: 'Fallback-only create accessors emit a warning',
73
+ },
74
+ ],
75
+ rule: incompleteAccessorForStandardOp,
76
+ });
@@ -0,0 +1,39 @@
1
+ import { incompleteCrud } from '../rules/incomplete-crud.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const incompleteCrudTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'clean.ts',
10
+ sourceCode: `import { Result, resource } from '@ontrails/core';
11
+ import { store } from '@ontrails/store';
12
+ import { crud } from '@ontrails/store/trails';
13
+ import { z } from 'zod';
14
+
15
+ const db = store({
16
+ notes: {
17
+ identity: 'id',
18
+ schema: z.object({
19
+ id: z.string(),
20
+ title: z.string(),
21
+ }),
22
+ },
23
+ });
24
+
25
+ const notesResource = resource('db.notes', {
26
+ create: () => Result.ok({}),
27
+ mock: () => ({}),
28
+ });
29
+
30
+ const [createNote, readNote, updateNote, deleteNote, listNote] = crud(
31
+ db.tables.notes,
32
+ notesResource
33
+ );`,
34
+ },
35
+ name: 'Full CRUD coverage stays quiet',
36
+ },
37
+ ],
38
+ rule: incompleteCrud,
39
+ });
@@ -0,0 +1,89 @@
1
+ export { activationOrphanTrail } from './activation-orphan.trail.js';
2
+ export { capturedKernelTrail } from './captured-kernel.trail.js';
3
+ export { cliCommandRouteCoherenceTrail } from './cli-command-route-coherence.trail.js';
4
+ export { circularRefsTrail } from './circular-refs.trail.js';
5
+ export { entityExistsTrail } from './entity-exists.trail.js';
6
+ export { contextNoSurfaceTypesTrail } from './context-no-surface-types.trail.js';
7
+ export { composesDeclarationsTrail } from './composes-declarations.trail.js';
8
+ export { deadInternalTrailTrail } from './dead-internal-trail.trail.js';
9
+ export { deadPublicTrailTrail } from './dead-public-trail.trail.js';
10
+ export { deprecationWithoutGuidanceTrail } from './deprecation-without-guidance.trail.js';
11
+ export { duplicatePublicContractTrail } from './duplicate-public-contract.trail.js';
12
+ export { draftFileMarkingTrail } from './draft-file-marking.trail.js';
13
+ export { draftVisibleDebtTrail } from './draft-visible-debt.trail.js';
14
+ export { duplicateExportedSymbolTrail } from './duplicate-exported-symbol.trail.js';
15
+ export { errorMappingCompletenessTrail } from './error-mapping-completeness.trail.js';
16
+ export { exampleValidTrail } from './example-valid.trail.js';
17
+ export { firesDeclarationsTrail } from './fires-declarations.trail.js';
18
+ export { forkWithoutPreservedImplementationTrail } from './fork-without-preserved-implementation.trail.js';
19
+ export { governedSymbolResidueTrail } from './governed-symbol-residue.trail.js';
20
+ export { implementationReturnsResultTrail } from './implementation-returns-result.trail.js';
21
+ export { incompleteAccessorForStandardOpTrail } from './incomplete-accessor-for-standard-op.trail.js';
22
+ export { incompleteCrudTrail } from './incomplete-crud.trail.js';
23
+ export { intentPropagationTrail } from './intent-propagation.trail.js';
24
+ export { layerFieldNameDriftTrail } from './layer-field-name-drift.trail.js';
25
+ export { libraryProjectionCoherenceTrail } from './library-projection-coherence.trail.js';
26
+ export { markerSchemaUnsupportedTrail } from './marker-schema-unsupported.trail.js';
27
+ export { missingVisibilityTrail } from './missing-visibility.trail.js';
28
+ export { missingReconcileTrail } from './missing-reconcile.trail.js';
29
+ export { onReferencesExistTrail } from './on-references-exist.trail.js';
30
+ export { noDevPermitInSourceTrail } from './no-dev-permit-in-source.trail.js';
31
+ export { noDestructuredComposeTrail } from './no-destructured-compose.trail.js';
32
+ export { noLegacyCliAliasExportTrail } from './no-legacy-cli-alias-export.trail.js';
33
+ export { noLegacyLayerImportsTrail } from './no-legacy-layer-imports.trail.js';
34
+ export { noDirectImplementationCallTrail } from './no-direct-implementation-call.trail.js';
35
+ export { noNativeErrorResultTrail } from './no-native-error-result.trail.js';
36
+ export { noRedundantResultErrorWrapTrail } from './no-redundant-result-error-wrap.trail.js';
37
+ export { noRetiredCrossVocabularyTrail } from './no-retired-cross-vocabulary.trail.js';
38
+ export { noSyncResultAssumptionTrail } from './no-sync-result-assumption.trail.js';
39
+ export { noThrowInDetourRecoverTrail } from './no-throw-in-detour-recover.trail.js';
40
+ export { noThrowInImplementationTrail } from './no-throw-in-implementation.trail.js';
41
+ export { noTopLevelSurfaceTrail } from './no-top-level-surface.trail.js';
42
+ export { orphanedSignalTrail } from './orphaned-signal.trail.js';
43
+ export { ownerProjectionParityTrail } from './owner-projection-parity.trail.js';
44
+ export { pendingForceTrail } from './pending-force.trail.js';
45
+ export { permitGovernanceTrail } from './permit-governance.trail.js';
46
+ export { preferSchemaInferenceTrail } from './prefer-schema-inference.trail.js';
47
+ export { publicExportExampleCoverageTrail } from './public-export-example-coverage.trail.js';
48
+ export { publicInternalDeepImportsTrail } from './public-internal-deep-imports.trail.js';
49
+ export { publicOutputSchemaTrail } from './public-output-schema.trail.js';
50
+ export { publicUnionOutputDiscriminantsTrail } from './public-union-output-discriminants.trail.js';
51
+ export { readIntentFiresTrail } from './read-intent-fires.trail.js';
52
+ export { referenceExistsTrail } from './reference-exists.trail.js';
53
+ export { resolvedImportBoundaryTrail } from './resolved-import-boundary.trail.js';
54
+ export { resourceDeclarationsTrail } from './resource-declarations.trail.js';
55
+ export { resourceIdGrammarTrail } from './resource-id-grammar.trail.js';
56
+ export { resourceExistsTrail } from './resource-exists.trail.js';
57
+ export { resourceMockCoverageTrail } from './resource-mock-coverage.trail.js';
58
+ export { scheduledDestroyIntentTrail } from './scheduled-destroy-intent.trail.js';
59
+ export { signalGraphCoachingTrail } from './signal-graph-coaching.trail.js';
60
+ export { staticResourceAccessorPreferenceTrail } from './static-resource-accessor-preference.trail.js';
61
+ export { surfaceOverlayCoherenceTrail } from './surface-overlay-coherence.trail.js';
62
+ export { surfaceTrailheadCoherenceTrail } from './surface-trailhead-coherence.trail.js';
63
+ export { trailForkCoachingTrail } from './trail-fork-coaching.trail.js';
64
+ export { trailheadOverrideDivergenceTrail } from './trailhead-override-divergence.trail.js';
65
+ export { unmaterializedActivationSourceTrail } from './unmaterialized-activation-source.trail.js';
66
+ export { unreachableDetourShadowingTrail } from './unreachable-detour-shadowing.trail.js';
67
+ export { validDetourContractTrail } from './valid-detour-contract.trail.js';
68
+ export { validDescribeRefsTrail } from './valid-describe-refs.trail.js';
69
+ export { versionGapTrail } from './version-gap.trail.js';
70
+ export { versionPinnedComposeTrail } from './version-pinned-compose.trail.js';
71
+ export { versionWithoutExamplesTrail } from './version-without-examples.trail.js';
72
+ export { wardenExportSymmetryTrail } from './warden-export-symmetry.trail.js';
73
+ export { wardenRulesUseAstTrail } from './warden-rules-use-ast.trail.js';
74
+ export { webhookRouteCollisionTrail } from './webhook-route-collision.trail.js';
75
+
76
+ export {
77
+ diagnosticSchema,
78
+ projectAwareRuleInput,
79
+ ruleInput,
80
+ ruleOutput,
81
+ topoAwareRuleInput,
82
+ } from './schema.js';
83
+ export type {
84
+ ProjectAwareRuleInput,
85
+ RuleInput,
86
+ RuleOutput,
87
+ TopoAwareRuleInput,
88
+ } from './schema.js';
89
+ export { wrapRule, wrapTopoRule } from './wrap-rule.js';
@@ -0,0 +1,30 @@
1
+ import { intentPropagation } from '../rules/intent-propagation.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const intentPropagationTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'clean.ts',
10
+ knownTrailIds: ['entity.read', 'entity.lookup'],
11
+ sourceCode: `trail('entity.read', {
12
+ intent: 'read',
13
+ composes: ['entity.lookup'],
14
+ implementation: async (_input, ctx) => ctx.compose('entity.lookup', {}),
15
+ });
16
+
17
+ trail('entity.lookup', {
18
+ intent: 'read',
19
+ implementation: async () => Result.ok({}),
20
+ });`,
21
+ trailIntentsById: {
22
+ 'entity.lookup': 'read',
23
+ 'entity.read': 'read',
24
+ },
25
+ },
26
+ name: 'Read trails may compose other read trails',
27
+ },
28
+ ],
29
+ rule: intentPropagation,
30
+ });
@@ -0,0 +1,39 @@
1
+ import { layerFieldNameDrift } from '../rules/layer-field-name-drift.js';
2
+ import { wrapRule } from './wrap-rule.js';
3
+
4
+ export const layerFieldNameDriftTrail = wrapRule({
5
+ examples: [
6
+ {
7
+ expected: { diagnostics: [] },
8
+ input: {
9
+ filePath: 'packages/cli/src/build.ts',
10
+ sourceCode: `import { LAYER_FIELD_RESERVED_NAMES } from '@ontrails/core';
11
+
12
+ const collides = LAYER_FIELD_RESERVED_NAMES.has('all');
13
+ `,
14
+ },
15
+ name: 'Allows shared core reserved-name set',
16
+ },
17
+ {
18
+ expected: {
19
+ diagnostics: [
20
+ {
21
+ filePath: 'packages/cli/src/build.ts',
22
+ line: 1,
23
+ message:
24
+ 'layer-field-name-drift: surface-local reserved name set "META_FLAG_CANDIDATES" can make layer input fields project differently across surfaces. Import LAYER_FIELD_RESERVED_NAMES from @ontrails/core instead.',
25
+ rule: 'layer-field-name-drift',
26
+ severity: 'error',
27
+ },
28
+ ],
29
+ },
30
+ input: {
31
+ filePath: 'packages/cli/src/build.ts',
32
+ sourceCode: `const META_FLAG_CANDIDATES = new Set(['all']);
33
+ `,
34
+ },
35
+ name: 'Flags surface-local reserved-name sets',
36
+ },
37
+ ],
38
+ rule: layerFieldNameDrift,
39
+ });
@@ -0,0 +1,43 @@
1
+ import { Result, topo, trail } from '@ontrails/core';
2
+ import { z } from 'zod';
3
+
4
+ import { libraryProjectionCoherence } from '../rules/library-projection-coherence.js';
5
+ import { wrapTopoRule } from './wrap-rule.js';
6
+
7
+ const output = z.object({ ok: z.boolean() });
8
+
9
+ const dotted = trail('widget.ping', {
10
+ implementation: () => Result.ok({ ok: true }),
11
+ input: z.object({}),
12
+ output,
13
+ });
14
+
15
+ const kebab = trail('widget-ping', {
16
+ implementation: () => Result.ok({ ok: true }),
17
+ input: z.object({}),
18
+ output,
19
+ });
20
+
21
+ export const libraryProjectionCoherenceTrail = wrapTopoRule({
22
+ examples: [
23
+ {
24
+ expected: {
25
+ diagnostics: [
26
+ {
27
+ filePath: '<topo>',
28
+ line: 1,
29
+ message:
30
+ 'Library projection export collision on "widgetPing": trails "widget-ping", "widget.ping" derive the same package export. Rename one trail or add a library export override before materializing the generated package.',
31
+ rule: 'library-projection-coherence',
32
+ severity: 'error',
33
+ },
34
+ ],
35
+ },
36
+ input: {
37
+ topo: topo('library-projection-coherence', { dotted, kebab }),
38
+ },
39
+ name: 'Library export collision',
40
+ },
41
+ ],
42
+ rule: libraryProjectionCoherence,
43
+ });