@starci/eslint-canon-be 3.18.4 → 3.19.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 (208) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/dist/comments.js +1 -1
  3. package/dist/explicit-surface.js +1 -1
  4. package/dist/index.js +1 -1
  5. package/dist/jwt-alg.js +1 -1
  6. package/dist/lib/edition.d.ts +1 -1
  7. package/dist/lib/edition.js +1 -1
  8. package/dist/lib/hfs.d.ts +0 -6
  9. package/dist/lib/hfs.js +7 -5
  10. package/dist/lib/runtime-root.d.ts +6 -1
  11. package/dist/lib/runtime-root.js +8 -2
  12. package/dist/lib/subject-values.js +1 -1
  13. package/dist/module-layering.js +2 -2
  14. package/dist/project-graph.js +1 -1
  15. package/dist/third-party-owner.js +1 -1
  16. package/package.json +3 -1
  17. package/runtime/bundle.json +1 -190
  18. package/runtime/scripts/api/git/recorded-lines.mjs +5 -5
  19. package/runtime/scripts/hfs/project-graph.mjs +6 -6
  20. package/runtime/scripts/hfs/project-rule.mjs +3 -3
  21. package/runtime/config.example.yaml +0 -194
  22. package/runtime/engine/by-code-unit.mjs +0 -12
  23. package/runtime/engine/config.mjs +0 -461
  24. package/runtime/engine/invalid-config.mjs +0 -15
  25. package/runtime/engine/model-config.mjs +0 -112
  26. package/runtime/engine/orca-config.mjs +0 -34
  27. package/runtime/engine/plain-object.mjs +0 -5
  28. package/runtime/engine/release-config.mjs +0 -32
  29. package/runtime/engine/removed-vocabulary.mjs +0 -27
  30. package/runtime/engine/resources-config.mjs +0 -59
  31. package/runtime/engine/runtime-root.mjs +0 -138
  32. package/runtime/engine/secrets.mjs +0 -202
  33. package/runtime/engine/sonar-config.mjs +0 -24
  34. package/runtime/engine/temp-root.mjs +0 -26
  35. package/runtime/engine/yaml.mjs +0 -161
  36. package/runtime/knowledge/grammars/index.yaml +0 -114
  37. package/runtime/knowledge/hfs/canon-pins.yaml +0 -720
  38. package/runtime/knowledge/hfs/fe-stack.yaml +0 -272
  39. package/runtime/knowledge/hfs/rules.yaml +0 -6760
  40. package/runtime/knowledge/hfs/slots.yaml +0 -2783
  41. package/runtime/knowledge/patterns/fe/folder.yaml +0 -425
  42. package/runtime/knowledge/sonar-gate.yaml +0 -151
  43. package/runtime/modules/kernel/removed-vocabulary.yaml +0 -458
  44. package/runtime/modules/models/registry.yaml +0 -221
  45. package/runtime/modules/models/runtimes.yaml +0 -556
  46. package/runtime/modules/models/tiers.yaml +0 -66
  47. package/runtime/scripts/api/git/cat-file.mjs +0 -4
  48. package/runtime/scripts/api/git/config-get.mjs +0 -9
  49. package/runtime/scripts/api/git/diff.mjs +0 -4
  50. package/runtime/scripts/api/git/lib.mjs +0 -80
  51. package/runtime/scripts/api/git/ls-files.mjs +0 -5
  52. package/runtime/scripts/api/git/ls-tree.mjs +0 -4
  53. package/runtime/scripts/api/git/merge-base.mjs +0 -8
  54. package/runtime/scripts/api/git/remote.mjs +0 -4
  55. package/runtime/scripts/api/git/rev-parse-query.mjs +0 -4
  56. package/runtime/scripts/api/git/show.mjs +0 -5
  57. package/runtime/scripts/api/git/tag.mjs +0 -4
  58. package/runtime/scripts/hfs/allows.mjs +0 -77
  59. package/runtime/scripts/hfs/architecture/ast-walks.mjs +0 -250
  60. package/runtime/scripts/hfs/architecture/automatic-gates.mjs +0 -103
  61. package/runtime/scripts/hfs/architecture/backend-app-files.mjs +0 -114
  62. package/runtime/scripts/hfs/architecture/backend.mjs +0 -462
  63. package/runtime/scripts/hfs/architecture/background-unowned.mjs +0 -254
  64. package/runtime/scripts/hfs/architecture/canon-clones.mjs +0 -291
  65. package/runtime/scripts/hfs/architecture/canon-jsx-clones.mjs +0 -224
  66. package/runtime/scripts/hfs/architecture/client-reaches-server.mjs +0 -102
  67. package/runtime/scripts/hfs/architecture/clones.mjs +0 -287
  68. package/runtime/scripts/hfs/architecture/component-tiers.mjs +0 -161
  69. package/runtime/scripts/hfs/architecture/config-unread.mjs +0 -16
  70. package/runtime/scripts/hfs/architecture/config.mjs +0 -407
  71. package/runtime/scripts/hfs/architecture/connection-map.mjs +0 -350
  72. package/runtime/scripts/hfs/architecture/constructor-deps.mjs +0 -115
  73. package/runtime/scripts/hfs/architecture/context-coupling.mjs +0 -117
  74. package/runtime/scripts/hfs/architecture/context-map.mjs +0 -355
  75. package/runtime/scripts/hfs/architecture/context-owner.mjs +0 -102
  76. package/runtime/scripts/hfs/architecture/context-platform-tables.mjs +0 -65
  77. package/runtime/scripts/hfs/architecture/context-transaction.mjs +0 -75
  78. package/runtime/scripts/hfs/architecture/contract-bounds.mjs +0 -72
  79. package/runtime/scripts/hfs/architecture/contract-fixture-guard.mjs +0 -177
  80. package/runtime/scripts/hfs/architecture/contracts-readonly.mjs +0 -360
  81. package/runtime/scripts/hfs/architecture/contracts.mjs +0 -489
  82. package/runtime/scripts/hfs/architecture/cross-app-duplicate.mjs +0 -81
  83. package/runtime/scripts/hfs/architecture/dead-exports-bindings.mjs +0 -173
  84. package/runtime/scripts/hfs/architecture/dead-exports.mjs +0 -420
  85. package/runtime/scripts/hfs/architecture/default-deny.mjs +0 -175
  86. package/runtime/scripts/hfs/architecture/doc-language.mjs +0 -45
  87. package/runtime/scripts/hfs/architecture/entity-registry.mjs +0 -51
  88. package/runtime/scripts/hfs/architecture/entrypoint.mjs +0 -75
  89. package/runtime/scripts/hfs/architecture/error-codes.mjs +0 -54
  90. package/runtime/scripts/hfs/architecture/error-masked.mjs +0 -78
  91. package/runtime/scripts/hfs/architecture/fe-slot-allows.mjs +0 -44
  92. package/runtime/scripts/hfs/architecture/feature-shape.mjs +0 -60
  93. package/runtime/scripts/hfs/architecture/framework-pinned.mjs +0 -41
  94. package/runtime/scripts/hfs/architecture/frontend-block-render.mjs +0 -112
  95. package/runtime/scripts/hfs/architecture/frontend-grammar.mjs +0 -193
  96. package/runtime/scripts/hfs/architecture/frontend-routing.mjs +0 -198
  97. package/runtime/scripts/hfs/architecture/frontend-world-render.mjs +0 -368
  98. package/runtime/scripts/hfs/architecture/frontend-world.mjs +0 -374
  99. package/runtime/scripts/hfs/architecture/frontend.mjs +0 -248
  100. package/runtime/scripts/hfs/architecture/function-spec-providers.mjs +0 -185
  101. package/runtime/scripts/hfs/architecture/hfs-graph.mjs +0 -77
  102. package/runtime/scripts/hfs/architecture/hfs.mjs +0 -394
  103. package/runtime/scripts/hfs/architecture/hooks-are-hooks.mjs +0 -118
  104. package/runtime/scripts/hfs/architecture/i18n-keys.mjs +0 -213
  105. package/runtime/scripts/hfs/architecture/identity.mjs +0 -121
  106. package/runtime/scripts/hfs/architecture/index.mjs +0 -402
  107. package/runtime/scripts/hfs/architecture/injection-token-exported.mjs +0 -69
  108. package/runtime/scripts/hfs/architecture/jwt-ast.mjs +0 -231
  109. package/runtime/scripts/hfs/architecture/machine-ast.mjs +0 -232
  110. package/runtime/scripts/hfs/architecture/managed-scripts.mjs +0 -32
  111. package/runtime/scripts/hfs/architecture/module-per-transport.mjs +0 -237
  112. package/runtime/scripts/hfs/architecture/next-data-contract.mjs +0 -126
  113. package/runtime/scripts/hfs/architecture/next-data-inference.mjs +0 -192
  114. package/runtime/scripts/hfs/architecture/next-data-key.mjs +0 -374
  115. package/runtime/scripts/hfs/architecture/next-data-symbols.mjs +0 -26
  116. package/runtime/scripts/hfs/architecture/next-data.mjs +0 -425
  117. package/runtime/scripts/hfs/architecture/operation-contract-roots.mjs +0 -55
  118. package/runtime/scripts/hfs/architecture/owners.mjs +0 -142
  119. package/runtime/scripts/hfs/architecture/package-shape.mjs +0 -92
  120. package/runtime/scripts/hfs/architecture/presentation.mjs +0 -173
  121. package/runtime/scripts/hfs/architecture/reachability.mjs +0 -330
  122. package/runtime/scripts/hfs/architecture/register-once.mjs +0 -212
  123. package/runtime/scripts/hfs/architecture/registration.mjs +0 -372
  124. package/runtime/scripts/hfs/architecture/render-graph.mjs +0 -449
  125. package/runtime/scripts/hfs/architecture/render-prop-across-server.mjs +0 -58
  126. package/runtime/scripts/hfs/architecture/required-files.mjs +0 -237
  127. package/runtime/scripts/hfs/architecture/root-packages.mjs +0 -78
  128. package/runtime/scripts/hfs/architecture/route-files-thin.mjs +0 -133
  129. package/runtime/scripts/hfs/architecture/schema-owner.mjs +0 -288
  130. package/runtime/scripts/hfs/architecture/server-action.mjs +0 -78
  131. package/runtime/scripts/hfs/architecture/side-boundary.mjs +0 -13
  132. package/runtime/scripts/hfs/architecture/source-names-shape.mjs +0 -320
  133. package/runtime/scripts/hfs/architecture/source-names.mjs +0 -393
  134. package/runtime/scripts/hfs/architecture/sql-keys.mjs +0 -344
  135. package/runtime/scripts/hfs/architecture/sql-owner.mjs +0 -291
  136. package/runtime/scripts/hfs/architecture/sql-returning.mjs +0 -76
  137. package/runtime/scripts/hfs/architecture/sql-token-forms.mjs +0 -117
  138. package/runtime/scripts/hfs/architecture/sql-tokens.mjs +0 -587
  139. package/runtime/scripts/hfs/architecture/staged-consumers.mjs +0 -42
  140. package/runtime/scripts/hfs/architecture/surface-nesting.mjs +0 -127
  141. package/runtime/scripts/hfs/architecture/surface.mjs +0 -88
  142. package/runtime/scripts/hfs/architecture/symbols.mjs +0 -273
  143. package/runtime/scripts/hfs/architecture/test-world-files.mjs +0 -263
  144. package/runtime/scripts/hfs/architecture/tiers.mjs +0 -256
  145. package/runtime/scripts/hfs/architecture/transport-owner.mjs +0 -248
  146. package/runtime/scripts/hfs/architecture/type-context.mjs +0 -335
  147. package/runtime/scripts/hfs/architecture/typescript.mjs +0 -477
  148. package/runtime/scripts/hfs/architecture/unit-spec-providers.mjs +0 -165
  149. package/runtime/scripts/hfs/declaration-shape.mjs +0 -196
  150. package/runtime/scripts/hfs/declaration-slots.mjs +0 -89
  151. package/runtime/scripts/hfs/edition-slots.mjs +0 -80
  152. package/runtime/scripts/hfs/explicit-surface-rule.mjs +0 -59
  153. package/runtime/scripts/hfs/linear-text.mjs +0 -30
  154. package/runtime/scripts/hfs/manifest-shape.mjs +0 -474
  155. package/runtime/scripts/hfs/param-names.mjs +0 -13
  156. package/runtime/scripts/hfs/path-findings.mjs +0 -167
  157. package/runtime/scripts/hfs/repo-identity.mjs +0 -89
  158. package/runtime/scripts/hfs/rule-catalog.mjs +0 -458
  159. package/runtime/scripts/hfs/rule-params-shape.mjs +0 -103
  160. package/runtime/scripts/hfs/rules/database-constants.mjs +0 -25
  161. package/runtime/scripts/hfs/rules/database-migrations.mjs +0 -684
  162. package/runtime/scripts/hfs/rules/fe-no-tests.mjs +0 -68
  163. package/runtime/scripts/hfs/rules/read.mjs +0 -45
  164. package/runtime/scripts/hfs/rules/secrets.mjs +0 -79
  165. package/runtime/scripts/hfs/rules/spec-placement.mjs +0 -28
  166. package/runtime/scripts/hfs/slot-app-view.mjs +0 -97
  167. package/runtime/scripts/hfs/slot-classify.mjs +0 -69
  168. package/runtime/scripts/hfs/slot-errors.mjs +0 -12
  169. package/runtime/scripts/hfs/slot-imports.mjs +0 -98
  170. package/runtime/scripts/hfs/slot-manifest-shape.mjs +0 -111
  171. package/runtime/scripts/hfs/slot-match.mjs +0 -164
  172. package/runtime/scripts/hfs/slot-path.mjs +0 -6
  173. package/runtime/scripts/hfs/slot-required.mjs +0 -95
  174. package/runtime/scripts/hfs/slot-semantic-problems.mjs +0 -175
  175. package/runtime/scripts/hfs/slot-side-problems.mjs +0 -32
  176. package/runtime/scripts/hfs/slots.mjs +0 -306
  177. package/runtime/scripts/hfs/test-world-slot.mjs +0 -5
  178. package/runtime/scripts/hfs/trailing-slashes.mjs +0 -8
  179. package/runtime/scripts/hfs/typescript-programs.mjs +0 -95
  180. package/runtime/scripts/hfs/view.mjs +0 -180
  181. package/runtime/scripts/lib/declaration-surface.mjs +0 -166
  182. package/runtime/scripts/lib/dockerfile.mjs +0 -164
  183. package/runtime/scripts/lib/env.mjs +0 -18
  184. package/runtime/scripts/lib/event-contract.mjs +0 -102
  185. package/runtime/scripts/lib/git-hooks-dir.mjs +0 -30
  186. package/runtime/scripts/lib/git.mjs +0 -35
  187. package/runtime/scripts/lib/glob.mjs +0 -32
  188. package/runtime/scripts/lib/grammar-lint.mjs +0 -57
  189. package/runtime/scripts/lib/i18n.mjs +0 -82
  190. package/runtime/scripts/lib/in-order.mjs +0 -90
  191. package/runtime/scripts/lib/json-clone.mjs +0 -70
  192. package/runtime/scripts/lib/json.mjs +0 -44
  193. package/runtime/scripts/lib/language.mjs +0 -233
  194. package/runtime/scripts/lib/list.mjs +0 -26
  195. package/runtime/scripts/lib/mutation-fence.mjs +0 -20
  196. package/runtime/scripts/lib/package-at.mjs +0 -62
  197. package/runtime/scripts/lib/path-key.mjs +0 -124
  198. package/runtime/scripts/lib/read-text.mjs +0 -47
  199. package/runtime/scripts/lib/regex.mjs +0 -3
  200. package/runtime/scripts/lib/rule-packs.mjs +0 -243
  201. package/runtime/scripts/lib/same-text.mjs +0 -4
  202. package/runtime/scripts/lib/secret-patterns.mjs +0 -230
  203. package/runtime/scripts/lib/sops-envelope.mjs +0 -212
  204. package/runtime/scripts/lib/stack-services.mjs +0 -191
  205. package/runtime/scripts/lib/ts-analysis.mjs +0 -39
  206. package/runtime/scripts/lib/ts-ast.mjs +0 -63
  207. package/runtime/scripts/lib/walk.mjs +0 -45
  208. package/runtime/scripts/lib/yaml-cached.mjs +0 -14
@@ -1,684 +0,0 @@
1
- // database-migrations.mjs - L02 migration name, UTC ordering and base-branch immutability checks. Git reads go
2
- // through the runtime API call files, and specs may inject the same small runner contract used by database.mjs.
3
- import { lsTree } from '../../api/git/ls-tree.mjs';
4
- import { mergeBase } from '../../api/git/merge-base.mjs';
5
- import { show } from '../../api/git/show.mjs';
6
- import { tag } from '../../api/git/tag.mjs';
7
- import { withoutGitLocalEnv } from '../../lib/git.mjs';
8
- import { eachInOrder, findInOrder } from '../../lib/in-order.mjs';
9
- import { sameText } from '../../lib/same-text.mjs';
10
- import { found, readJson, readText } from './read.mjs';
11
- import { DB_DESTRUCTIVE_RULING_UNPROVEN, DB_MIGRATION_DESTRUCTIVE, DB_MIGRATION_SHAPE, isActiveMigration, MIGRATIONS_ARCHIVE_DIR, MIGRATIONS_DIR } from './database-constants.mjs';
12
- import path from 'node:path';
13
- import { fileURLToPath } from 'node:url';
14
- import { loadTypescript } from '../../lib/package-at.mjs';
15
- import { isConstVariable } from '../../lib/ts-ast.mjs';
16
- import { lexicalChecker, unwrapExpression } from '../../lib/ts-analysis.mjs';
17
- const HERE = path.dirname(fileURLToPath(import.meta.url));
18
- const MIGRATION_PLAIN = /[a-z0-9]+(?:-[a-z0-9]+)*/;
19
- const MIGRATION_CONTRACT_TAIL = /contract_[a-z0-9]+(?:[-_][a-z0-9]+)*/;
20
- const MIGRATION_SLUG = [MIGRATION_PLAIN.source, MIGRATION_CONTRACT_TAIL.source, `${MIGRATION_PLAIN.source}_${MIGRATION_CONTRACT_TAIL.source}`].join('|');
21
- const MIGRATION_NAME = new RegExp(String.raw `^(\d{14})_(${MIGRATION_SLUG})\.sql$`);
22
- export const isMigrationName = (name) => MIGRATION_NAME.test(name);
23
- const RESTAMP_HEADER = /^-- starci:restamp (\d{14}) (\d{14})(?:\r?\n|$)/;
24
- const withoutRestampHeader = (text) => text?.replace(RESTAMP_HEADER, '') ?? null;
25
- /** `<ts14>` -> the UTC instant it names, or null when the digits are no real time (month 13, day 32, ...). */
26
- export function migrationStamp(text) {
27
- const [year, month, day, hour, minute, second] = [Number(text.slice(0, 4)), ...[4, 6, 8, 10, 12].map((at) => Number(text.slice(at, at + 2)))];
28
- const stamp = Date.UTC(year, month - 1, day, hour, minute, second);
29
- const date = new Date(stamp);
30
- return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
31
- && date.getUTCHours() === hour && date.getUTCMinutes() === minute && date.getUTCSeconds() === second ? stamp : null;
32
- }
33
- /** The three git reads L02 makes: (args, {cwd}) -> {ok, stdout}. */
34
- export function defaultGit(args, { cwd }) {
35
- const [verb, ...rest] = args;
36
- const env = withoutGitLocalEnv(process.env);
37
- if (verb === 'merge-base') {
38
- const sha = mergeBase(cwd, rest[0], rest[1]);
39
- return { ok: sha !== null, stdout: sha ?? '' };
40
- }
41
- if (verb === 'previous-release')
42
- return previousReleaseTag(cwd, env, rest[0]);
43
- let call = show;
44
- if (verb === 'ls-tree')
45
- call = lsTree;
46
- const result = call(rest, { cwd, env, maxBuffer: 64 * 1024 * 1024 });
47
- return { ok: !result.error && result.status === 0, stdout: result.stdout };
48
- }
49
- /** The nearest release tag before HEAD: the newest version among the tags HEAD contains that do not point at HEAD itself. `pattern` is a tag glob (v*). */
50
- function previousReleaseTag(cwd, env, pattern) {
51
- const listed = (args) => { const result = tag(args, { cwd, env }); return !result.error && result.status === 0 ? String(result.stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean) : []; };
52
- const here = new Set(listed(['--points-at', 'HEAD']));
53
- const previous = listed(['--merged', 'HEAD', '--list', pattern, '--sort=-v:refname']).find((name) => !here.has(name));
54
- return { ok: previous !== undefined, stdout: previous ?? '' };
55
- }
56
- const runGit = (git, repoRoot, args) => Promise.resolve(git(args, { cwd: repoRoot }))
57
- .then((result) => ({ ok: result?.ok === true, stdout: String(result?.stdout ?? '') }));
58
- async function baseShaOf(git, repoRoot, base) {
59
- let found = null;
60
- await findInOrder(base ? [base] : ['origin/main', 'main'], async (ref) => {
61
- const result = await runGit(git, repoRoot, ['merge-base', 'HEAD', ref]);
62
- if (result.ok && result.stdout.trim())
63
- found = { ref, sha: result.stdout.trim() };
64
- return found !== null;
65
- });
66
- return found;
67
- }
68
- async function migrationFilesAt(git, repoRoot, sha) {
69
- const result = await runGit(git, repoRoot, ['ls-tree', '-r', '--name-only', '-z', sha, '--', MIGRATIONS_DIR]);
70
- if (!result.ok)
71
- return [];
72
- const prefix = `${MIGRATIONS_DIR}/`;
73
- return result.stdout.split('\0').filter((entry) => entry.startsWith(prefix));
74
- }
75
- async function baseFileText(git, repoRoot, sha, file) {
76
- // `./` reads the path from the app root, which is a folder of a larger repository when the app is nested in one (an example of the runtime).
77
- const result = await runGit(git, repoRoot, ['show', `${sha}:./${file}`]);
78
- return result.ok ? result.stdout : null;
79
- }
80
- function localMigrationFindings(local) {
81
- const findings = [];
82
- const stamps = new Map();
83
- for (const entry of local) {
84
- if (!entry.match) {
85
- findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is not named <ts14>_<kebab>.sql; a migration is created by \`npm run db:new\` (starci app db new), never renamed by hand`, { expected: '<ts14>_<kebab>.sql' }));
86
- continue;
87
- }
88
- const stamp = migrationStamp(entry.match[1]);
89
- if (stamp === null) {
90
- findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} carries ${entry.match[1]}, which is no valid UTC time; a migration stamp must name a valid UTC instant`, { stamp: entry.match[1] }));
91
- continue;
92
- }
93
- if (stamps.has(stamp))
94
- findings.push(found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} shares stamp ${entry.match[1]} with ${stamps.get(stamp)}; stamps are strictly increasing`, { stamp: entry.match[1], other: stamps.get(stamp) }));
95
- stamps.set(stamp, entry.file);
96
- }
97
- return findings;
98
- }
99
- /** HEAD owns the append boundary. Archived names retire the old chain, so a replacement baseline starts afresh. */
100
- function migrationHistory(files, retired, localNames) {
101
- const prefix = `${MIGRATIONS_DIR}/`;
102
- const onHead = new Set(files.filter(isActiveMigration).map((file) => file.slice(prefix.length)));
103
- const retiredNames = new Set([...retired, ...files.filter((file) => file.startsWith(`${MIGRATIONS_ARCHIVE_DIR}/`)).map((file) => file.slice(MIGRATIONS_ARCHIVE_DIR.length + 1))].filter((name) => !localNames.has(name)));
104
- const stamps = [...onHead].filter((name) => !retiredNames.has(name)).map((name) => MIGRATION_NAME.exec(name)?.[1]).filter((stamp) => Boolean(stamp)).map(migrationStamp).filter((stamp) => stamp !== null);
105
- return { onHead, latest: stamps.length ? Math.max(...stamps) : null };
106
- }
107
- function migrationOrderingFindings(local, history, restamped = new Set()) {
108
- return local.flatMap((entry) => {
109
- const stamp = entry.match ? migrationStamp(entry.match[1]) : null;
110
- if (history.onHead.has(entry.name) || restamped.has(entry.name) || stamp === null || history.latest === null || stamp > history.latest)
111
- return [];
112
- return [found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} is stamped ${entry.match[1]}, not after every migration already in repository history (latest active ${new Date(history.latest).toISOString()}); a new migration sorts after the committed active chain`, { stamp: entry.match[1], latest: new Date(history.latest).toISOString() })];
113
- });
114
- }
115
- /** A restamp changes only the version, and its header proves the explicit old->new map against repository SQL. */
116
- async function verifiedRestamps(local, files, repoRoot, git, sha) {
117
- const prefix = `${MIGRATIONS_DIR}/`;
118
- const active = files.filter(isActiveMigration).map((file) => file.slice(prefix.length));
119
- const claims = local.map((entry) => ({ ...entry, header: RESTAMP_HEADER.exec(readText(repoRoot, entry.file) ?? '') })).filter((entry) => entry.header);
120
- const accepted = [];
121
- await eachInOrder(claims, async (entry) => {
122
- const [, oldStamp, newStamp] = entry.header;
123
- if (!entry.match || entry.match[1] !== newStamp || migrationStamp(oldStamp) === null || oldStamp === newStamp)
124
- return;
125
- if (claims.filter((claim) => claim.header[1] === oldStamp).length !== 1)
126
- return;
127
- const names = active.filter((name) => name.startsWith(`${oldStamp}_`) && name.slice(14) === entry.name.slice(14));
128
- if (names.length !== 1 || local.some((candidate) => candidate.name === names[0]))
129
- return;
130
- const committed = await baseFileText(git, repoRoot, sha, `${prefix}${names[0]}`);
131
- if (committed === null || !sameText(withoutRestampHeader(readText(repoRoot, entry.file)), withoutRestampHeader(committed)))
132
- return;
133
- accepted.push({ source: names[0], destination: entry.name });
134
- });
135
- return accepted;
136
- }
137
- async function baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase) {
138
- if (!entry.match)
139
- return [];
140
- if (onBase.has(entry.name)) {
141
- const committed = await baseFileText(git, repoRoot, baseSha.sha, entry.file);
142
- const current = readText(repoRoot, entry.file);
143
- if (!sameText(current, committed))
144
- return [found(DB_MIGRATION_SHAPE, entry.file, `${entry.file} differs from its content on ${baseSha.ref}; a migration on the base branch is immutable - write a new migration`, { base: baseSha.ref })];
145
- }
146
- return [];
147
- }
148
- function removedMigrationFindings(local, retired, baseNames, baseSha) {
149
- const findings = [];
150
- for (const name of baseNames) {
151
- if (!local.some((entry) => entry.name === name) && !retired.has(name))
152
- findings.push(found(DB_MIGRATION_SHAPE, `${MIGRATIONS_DIR}/${name}`, `${MIGRATIONS_DIR}/${name} exists on ${baseSha.ref} but is gone here; a migration on the base branch is immutable - restore it`, { base: baseSha.ref }));
153
- }
154
- return findings;
155
- }
156
- /**
157
- * L02 findings for names, stamps, ordering and immutability of db/migrations/*.sql. `archived` are the files of
158
- * db/migrations/archive/ (app.db.migrations.archive): never judged, and a migration moved there at a baseline
159
- * cutover is retired from the ordering chain, not removed. New files append after HEAD's active migrations; timestamps
160
- * on archived migrations, remote branches and the wall clock do not constrain a replacement baseline.
161
- */
162
- export async function migrationShapeFindings({ repoRoot, migrations, archived = [], git, base }) {
163
- const prefix = `${MIGRATIONS_DIR}/`;
164
- const local = migrations.map((file) => {
165
- const name = file.startsWith(prefix) ? file.slice(prefix.length) : file;
166
- return { file, name, match: MIGRATION_NAME.exec(name) };
167
- });
168
- const findings = localMigrationFindings(local);
169
- const retired = new Set(archived.map((file) => file.slice(MIGRATIONS_ARCHIVE_DIR.length + 1)));
170
- const headFiles = await migrationFilesAt(git, repoRoot, 'HEAD');
171
- const baseSha = await baseShaOf(git, repoRoot, base);
172
- const baseFiles = baseSha ? await migrationFilesAt(git, repoRoot, baseSha.sha) : [];
173
- const restamps = await verifiedRestamps(local, baseSha ? baseFiles : headFiles, repoRoot, git, baseSha?.sha ?? 'HEAD');
174
- for (const restamp of restamps)
175
- retired.add(restamp.source);
176
- const history = migrationHistory(headFiles, retired, new Set(local.map((entry) => entry.name)));
177
- findings.push(...migrationOrderingFindings(local, history, new Set(restamps.map((entry) => entry.destination))));
178
- if (!baseSha)
179
- return findings;
180
- const baseNames = baseFiles.filter(isActiveMigration).map((file) => file.slice(prefix.length));
181
- const onBase = new Set(baseNames);
182
- await eachInOrder(local, async (entry) => {
183
- findings.push(...await baseMigrationEntryFindings(entry, repoRoot, git, baseSha, onBase));
184
- });
185
- findings.push(...removedMigrationFindings(local, retired, baseNames, baseSha));
186
- return findings;
187
- }
188
- const sqlName = (token) => token && ['word', 'ident'].includes(token.t) ? token.v : null;
189
- const sqlWord = (token, value) => token?.t === 'word' && token.v === value;
190
- function commentEnd(text, start) {
191
- if (text.startsWith('--', start)) {
192
- const end = text.indexOf('\n', start + 2);
193
- return end === -1 ? text.length : end;
194
- }
195
- if (!text.startsWith('/*', start))
196
- return null;
197
- let depth = 1;
198
- let index = start + 2;
199
- while (index < text.length && depth > 0) {
200
- if (text.startsWith('/*', index)) {
201
- depth += 1;
202
- index += 2;
203
- }
204
- else if (text.startsWith('*/', index)) {
205
- depth -= 1;
206
- index += 2;
207
- }
208
- else
209
- index += 1;
210
- }
211
- return index;
212
- }
213
- function quotedToken(text, start, quote, escaped = false) {
214
- let index = start + 1;
215
- let value = '';
216
- while (index < text.length) {
217
- if (text[index] === quote && text[index + 1] === quote) {
218
- value += quote;
219
- index += 2;
220
- }
221
- else if (text[index] === quote)
222
- return { value, end: index + 1 };
223
- else if (escaped && text[index] === '\\') {
224
- value += text[index + 1] ?? '';
225
- index += 2;
226
- }
227
- else {
228
- value += text[index];
229
- index += 1;
230
- }
231
- }
232
- return { value, end: index };
233
- }
234
- function sqlTokenAt(text, index) {
235
- const char = text[index];
236
- if (char === "'" || char === '"') {
237
- const token = quotedToken(text, index, char);
238
- return { t: char === '"' ? 'ident' : 'string', v: token.value, end: token.end };
239
- }
240
- if (/[eE]/.test(char) && text[index + 1] === "'") {
241
- const token = quotedToken(text, index + 1, "'", true);
242
- return { t: 'string', v: token.value, end: token.end };
243
- }
244
- const tag = char === '$' ? /^\$(?:[A-Za-z_]\w*)?\$/.exec(text.slice(index))?.[0] : null;
245
- if (tag) {
246
- const end = text.indexOf(tag, index + tag.length);
247
- return { t: 'body', v: text.slice(index + tag.length, end === -1 ? text.length : end), end: end === -1 ? text.length : end + tag.length };
248
- }
249
- const word = /^[A-Za-z_][A-Za-z0-9_$]*/.exec(text.slice(index))?.[0];
250
- if (word)
251
- return { t: 'word', v: word.toLowerCase(), end: index + word.length };
252
- const number = /^\d+(?:\.\d+)?/.exec(text.slice(index))?.[0];
253
- if (number)
254
- return { t: 'number', v: number, end: index + number.length };
255
- return { t: 'punct', v: char, end: index + 1 };
256
- }
257
- /** Synchronous SQL tokens; literal values stay internal and must never be copied to a finding. */
258
- export function databaseSqlTokens(text) {
259
- const tokens = [];
260
- let index = 0;
261
- let line = 1;
262
- while (index < text.length) {
263
- if (/\s/.test(text[index])) {
264
- if (text[index] === '\n')
265
- line += 1;
266
- index += 1;
267
- continue;
268
- }
269
- const end = commentEnd(text, index);
270
- if (end !== null) {
271
- line += text.slice(index, end).split('\n').length - 1;
272
- index = end;
273
- continue;
274
- }
275
- const token = sqlTokenAt(text, index);
276
- tokens.push({ t: token.t, v: token.v, line, index });
277
- line += text.slice(index, token.end).split('\n').length - 1;
278
- index = token.end;
279
- }
280
- return tokens;
281
- }
282
- /** Split executable SQL, retaining function bodies as opaque tokens until their language is known. */
283
- export function databaseSqlStatements(tokens) {
284
- const statements = [];
285
- let current = [];
286
- for (const token of tokens) {
287
- if (token.t === 'punct' && token.v === ';') {
288
- if (current.length)
289
- statements.push(current);
290
- current = [];
291
- }
292
- else
293
- current.push(token);
294
- }
295
- if (current.length)
296
- statements.push(current);
297
- return statements;
298
- }
299
- function executableStatementTokens(statement, depth) {
300
- const isDo = sqlWord(statement[0], 'do');
301
- const functionAt = statement.findIndex((token) => sqlWord(token, 'function') || sqlWord(token, 'procedure'));
302
- const isFunction = sqlWord(statement[0], 'create') && functionAt > 0 && functionAt < 4;
303
- if (!isDo && !isFunction)
304
- return statement;
305
- const languageAt = statement.findIndex((token) => sqlWord(token, 'language'));
306
- const language = statement[languageAt + 1]?.v ?? 'sql';
307
- if (languageAt !== -1 && !['sql', 'plpgsql'].includes(language))
308
- return statement;
309
- return statement.flatMap((token, index) => {
310
- const body = token.t === 'body' || (token.t === 'string' && (isDo || sqlWord(statement[index - 1], 'as')));
311
- if (!body)
312
- return [token];
313
- return databaseExecutableTokens(token.v, depth + 1).map((child) => ({ ...child, line: child.line + token.line - 1 }));
314
- });
315
- }
316
- /** SQL and PL/pgSQL bodies are scanned; comments, data literals and other function languages are opaque. */
317
- export function databaseExecutableTokens(text, depth = 0) {
318
- const tokens = databaseSqlTokens(text);
319
- if (depth > 8)
320
- return tokens;
321
- return databaseSqlStatements(tokens).flatMap((statement) => [...executableStatementTokens(statement, depth), { t: 'punct', v: ';' }]);
322
- }
323
- function nameAt(tokens, index) {
324
- const first = sqlName(tokens[index]);
325
- if (first === null)
326
- return null;
327
- const parts = [first];
328
- let next = index + 1;
329
- while (tokens[next]?.v === '.' && sqlName(tokens[next + 1]) !== null) {
330
- parts.push(sqlName(tokens[next + 1]));
331
- next += 2;
332
- }
333
- return { name: parts.join('.'), leaf: parts.at(-1), next };
334
- }
335
- const skipWords = (tokens, index, words) => {
336
- let next = index;
337
- while (words.some((word) => sqlWord(tokens[next], word)))
338
- next += 1;
339
- return next;
340
- };
341
- function dropObjects(tokens, start) {
342
- const kind = tokens[start + 1]?.v;
343
- if (!['table', 'role', 'user', 'schema', 'type', 'view', 'materialized', 'sequence', 'function', 'procedure', 'index', 'policy', 'trigger'].includes(kind))
344
- return [];
345
- let index = skipWords(tokens, start + 2, ['view', 'if', 'exists', 'concurrently']);
346
- const objects = [];
347
- while (index < tokens.length) {
348
- const object = nameAt(tokens, index);
349
- if (!object)
350
- break;
351
- objects.push({ ...object, kind, line: tokens[start].line });
352
- if (tokens[object.next]?.v !== ',')
353
- break;
354
- index = object.next + 1;
355
- }
356
- return objects;
357
- }
358
- function columnAlterObject(tokens, index, table, line) {
359
- let next = index + 1;
360
- if (sqlWord(tokens[next], 'column'))
361
- next += 1;
362
- const column = nameAt(tokens, next);
363
- if (!column)
364
- return null;
365
- const tail = tokens.slice(column.next);
366
- const type = sqlWord(tail[0], 'type') || (sqlWord(tail[0], 'set') && sqlWord(tail[1], 'data') && sqlWord(tail[2], 'type'));
367
- const notNull = sqlWord(tail[0], 'set') && sqlWord(tail[1], 'not') && sqlWord(tail[2], 'null');
368
- const defaultSet = tokens.some((token, at) => sqlWord(token, 'alter') && sqlName(tokens[at + 1 + Number(sqlWord(tokens[at + 1], 'column'))]) === column.leaf
369
- && sqlWord(tokens[at + 2 + Number(sqlWord(tokens[at + 1], 'column'))], 'set') && sqlWord(tokens[at + 3 + Number(sqlWord(tokens[at + 1], 'column'))], 'default'));
370
- if (!type && !(notNull && !defaultSet))
371
- return null;
372
- return { name: `${table.name}.${column.name}`, leaf: column.leaf, table: table.leaf, kind: 'column', alters: true, line };
373
- }
374
- function alteredColumn(table, column, line) {
375
- return { name: `${table.name}.${column.name}`, leaf: column.leaf, table: table.leaf, kind: 'column', line };
376
- }
377
- function tableActionObject(body, index, table, line) {
378
- if (sqlWord(body[index], 'drop')) {
379
- const constraint = sqlWord(body[index + 1], 'constraint');
380
- const at = skipWords(body, index + 1, ['column', 'constraint', 'if', 'exists']);
381
- if (sqlWord(body[at], 'default') || sqlWord(body[at], 'not'))
382
- return null;
383
- const column = nameAt(body, at);
384
- return column ? { ...alteredColumn(table, column, line), kind: constraint ? 'constraint' : 'column' } : null;
385
- }
386
- if (sqlWord(body[index], 'rename')) {
387
- const column = sqlWord(body[index + 1], 'column') ? nameAt(body, index + 2) : null;
388
- return column ? alteredColumn(table, column, line) : { ...table, kind: 'table', line };
389
- }
390
- return sqlWord(body[index], 'alter') ? columnAlterObject(body, index, table, line) : null;
391
- }
392
- function alterObjects(tokens, start) {
393
- const table = nameAt(tokens, skipWords(tokens, start + 2, ['if', 'exists', 'only']));
394
- if (!table)
395
- return [];
396
- const body = tokens.slice(table.next);
397
- return body.map((_token, index) => tableActionObject(body, index, table, tokens[start].line)).filter(Boolean);
398
- }
399
- function truncatedObjects(tokens, start) {
400
- const objects = [];
401
- let index = skipWords(tokens, start + 1, ['table', 'only']);
402
- while (index < tokens.length) {
403
- const table = nameAt(tokens, index);
404
- if (!table)
405
- break;
406
- objects.push({ ...table, kind: 'table', line: tokens[start].line });
407
- if (tokens[table.next]?.v !== ',')
408
- break;
409
- index = skipWords(tokens, table.next + 1, ['only']);
410
- }
411
- return objects;
412
- }
413
- function destructiveObjects(statement) {
414
- const objects = [];
415
- for (let index = 0; index < statement.length; index += 1) {
416
- if (sqlWord(statement[index], 'drop'))
417
- objects.push(...dropObjects(statement, index));
418
- else if (sqlWord(statement[index], 'truncate'))
419
- objects.push(...truncatedObjects(statement, index));
420
- else if (sqlWord(statement[index], 'alter') && sqlWord(statement[index + 1], 'table'))
421
- objects.push(...alterObjects(statement, index));
422
- else if (sqlWord(statement[index], 'alter') && ['type', 'schema', 'view', 'sequence', 'function', 'procedure', 'index'].includes(statement[index + 1]?.v)) {
423
- const object = nameAt(statement, index + 2);
424
- if (object && statement.slice(object.next).some((token) => sqlWord(token, 'rename')))
425
- objects.push({ ...object, kind: statement[index + 1].v, line: statement[index].line });
426
- }
427
- }
428
- return objects;
429
- }
430
- /** Keep the static parts of one SQL expression together across interpolation and string concatenation. */
431
- function sourceSqlText(ts, expression, checker, visiting = new Set()) {
432
- const node = unwrapExpression(ts, expression);
433
- if (ts.isStringLiteralLike(node))
434
- return node.text;
435
- if (ts.isTaggedTemplateExpression(node))
436
- return sourceSqlText(ts, node.template, checker, visiting);
437
- if (ts.isIdentifier(node)) {
438
- const declaration = checker.getSymbolAtLocation(node)?.valueDeclaration;
439
- if (!declaration || !ts.isVariableDeclaration(declaration) || !isConstVariable(ts, declaration)
440
- || !declaration.initializer || visiting.has(declaration))
441
- return null;
442
- return sourceSqlText(ts, declaration.initializer, checker, new Set([...visiting, declaration]));
443
- }
444
- if (ts.isTemplateExpression(node))
445
- return node.head.text + node.templateSpans.map((span) => `${sourceSqlText(ts, span.expression, checker, visiting) ?? ' '}${span.literal.text}`).join('');
446
- if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
447
- return `${sourceSqlText(ts, node.left, checker, visiting) ?? ' '}${sourceSqlText(ts, node.right, checker, visiting) ?? ' '}`;
448
- }
449
- return null;
450
- }
451
- /** SET CONSTRAINTS names have no table qualifier; every matching table's constraint is affected. */
452
- function globalConstraintNames(statement) {
453
- const names = new Set();
454
- for (let index = 0; index < statement.length; index += 1) {
455
- if (!sqlWord(statement[index], 'set') || !sqlWord(statement[index + 1], 'constraints'))
456
- continue;
457
- let at = index + 2;
458
- while (at < statement.length && !sqlWord(statement[at], 'all')) {
459
- const constraint = nameAt(statement, at);
460
- if (!constraint)
461
- break;
462
- names.add(constraint.leaf);
463
- if (statement[constraint.next]?.v !== ',')
464
- break;
465
- at = constraint.next + 1;
466
- }
467
- }
468
- return names;
469
- }
470
- const ENTITY_DECORATORS = new Set(['Entity', 'Table', 'ViewEntity']);
471
- /** Adds the table names a class decorator `@Entity(...)`, `@Table(...)` or `@ViewEntity(...)` spells to `tables`; true when such a decorator spells none. */
472
- function noteEntityTables(ts, decorator, tables) {
473
- const call = decorator.expression;
474
- const callee = ts.isCallExpression(call) ? call.expression : call;
475
- if (!ts.isIdentifier(callee) || !ENTITY_DECORATORS.has(callee.text))
476
- return false;
477
- const before = tables.size;
478
- const collect = (node) => {
479
- if (ts.isStringLiteralLike(node))
480
- for (const part of [node.text, node.text.split('.').at(-1)])
481
- tables.add(part);
482
- ts.forEachChild(node, collect);
483
- };
484
- if (ts.isCallExpression(call))
485
- for (const argument of call.arguments)
486
- collect(argument);
487
- return tables.size === before;
488
- }
489
- function sourceNameScopes(ts, text, file) {
490
- const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
491
- const checker = lexicalChecker(ts, source);
492
- const scopes = [];
493
- const entityNames = /\.entity\.[cm]?tsx?$/.test(file) ? new Set() : null;
494
- const entityTables = new Set();
495
- let implicitTable = false;
496
- const addSql = (sql) => {
497
- for (const statement of databaseSqlStatements(databaseSqlTokens(sql))) {
498
- const names = new Set(statement.filter((token) => sqlName(token) !== null).map((token) => token.v));
499
- if (entityNames)
500
- for (const name of names)
501
- entityNames.add(name);
502
- else {
503
- const constraints = new Set(statement.flatMap((token, index) => sqlWord(token, 'constraint') && sqlName(statement[index + 1]) !== null ? [statement[index + 1].v] : []));
504
- scopes.push({ names, constraints, globalConstraints: globalConstraintNames(statement) });
505
- }
506
- }
507
- };
508
- const visit = (node) => {
509
- const sql = sourceSqlText(ts, node, checker);
510
- if (sql !== null)
511
- addSql(sql);
512
- if (entityNames && ts.isIdentifier(node))
513
- entityNames.add(node.text);
514
- if (entityNames && ts.isDecorator(node))
515
- implicitTable = noteEntityTables(ts, node, entityTables) || implicitTable;
516
- ts.forEachChild(node, visit);
517
- };
518
- visit(source);
519
- // An entity names its table by the string of its @Entity/@Table decorator; a column property of the same word (`queue`) is no table reference.
520
- // An entity that names none (or has no such decorator) keeps the conservative identifier match.
521
- const tables = entityTables.size > 0 && !implicitTable ? entityTables : undefined;
522
- return entityNames ? [{ names: entityNames, tables, constraints: entityNames, globalConstraints: new Set() }] : scopes;
523
- }
524
- /**
525
- * Whether a be/src source references a destroyed object. A column (`<schema>.<table>.<column>`) is referenced only by a source that
526
- * names both its table and the column in one SQL statement or entity, so separate queries cannot supply each other's names.
527
- * SQL constraints require explicit constraint names, while entities retain their table/decorator association.
528
- * Other object kinds match their leaf name conservatively.
529
- */
530
- const referencesObject = (scopes, object) => scopes.some(({ names, tables, constraints, globalConstraints }) => (object.kind === 'constraint' && globalConstraints.has(object.leaf))
531
- || (object.kind === 'table' && tables !== undefined ? tables.has(object.leaf)
532
- : (object.kind === 'constraint' ? constraints : names).has(object.leaf)
533
- && (!['column', 'constraint'].includes(object.kind) || !object.table || (tables ?? names).has(object.table))));
534
- function destructiveObjectFinding(file, object, contract, references) {
535
- const reference = references.find(({ scopes }) => referencesObject(scopes, object));
536
- if (contract && !reference)
537
- return null;
538
- const reason = reference && contract ? `${reference.file} still references this object; remove the reference before the contract migration`
539
- : 'use a *_contract_* migration after the application stops using this object';
540
- return found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destructively changes ${object.name}; ${reason}`, { line: object.line, object: object.name, ...(reference ? { reference: reference.file } : {}) });
541
- }
542
- /** The `<table leaf>.<column leaf>` keys an ALTER TABLE ... ADD COLUMN statement adds, and `<table leaf>.*` for a CREATE TABLE. */
543
- function addedColumns(statement) {
544
- const added = [];
545
- for (let index = 0; index < statement.length - 1; index += 1) {
546
- if (sqlWord(statement[index], 'create')) {
547
- const at = skipWords(statement, index + 1, ['temp', 'temporary', 'unlogged']);
548
- const created = sqlWord(statement[at], 'table') ? nameAt(statement, skipWords(statement, at + 1, ['if', 'not', 'exists'])) : null;
549
- if (created)
550
- added.push(`${created.leaf}.*`);
551
- }
552
- if (!(sqlWord(statement[index], 'alter') && sqlWord(statement[index + 1], 'table')))
553
- continue;
554
- const table = nameAt(statement, skipWords(statement, index + 2, ['if', 'exists', 'only']));
555
- if (!table)
556
- continue;
557
- const body = statement.slice(table.next);
558
- body.forEach((token, at) => {
559
- if (!sqlWord(token, 'add'))
560
- return;
561
- const start = skipWords(body, at + 1, ['column', 'if', 'not', 'exists']);
562
- if (['constraint', 'primary', 'foreign', 'unique', 'check', 'exclude'].some((word) => sqlWord(body[start], word)))
563
- return;
564
- const column = nameAt(body, start);
565
- if (column)
566
- added.push(`${table.leaf}.${column.leaf}`);
567
- });
568
- }
569
- return added;
570
- }
571
- /** An ALTER of a column (SET NOT NULL, TYPE) the same migration added earlier changes no existing data: it is not destructive. */
572
- const alterOfNewColumn = (object, added) => object.alters === true && (added.has(`${object.table}.${object.leaf}`) || added.has(`${object.table}.*`));
573
- /** The destructive objects of one migration's SQL, in order, leaving out the alters of columns and tables the migration created itself. */
574
- function migrationDestructiveObjects(text) {
575
- const added = new Set();
576
- return databaseSqlStatements(databaseExecutableTokens(text)).flatMap((statement) => {
577
- for (const key of addedColumns(statement))
578
- added.add(key);
579
- return destructiveObjects(statement).filter((object) => !alterOfNewColumn(object, added));
580
- });
581
- }
582
- const CONTRACT_MIGRATION = /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/;
583
- /**
584
- * The owner rulings of hfs.json `db.destructiveRulings`, by migration file: the exact objects each may destroy outside a contract migration,
585
- * held only while the same proof a contract migration gets finds them unreferenced. The declaration shape judges reason and date.
586
- */
587
- function destructiveRulings(repoRoot) {
588
- const listed = readJson(repoRoot, 'hfs.json')?.db?.destructiveRulings;
589
- const rulings = new Map();
590
- for (const ruling of Array.isArray(listed) ? listed : []) {
591
- if (typeof ruling?.migration === 'string' && Array.isArray(ruling.objects))
592
- rulings.set(ruling.migration, new Set(ruling.objects.filter((name) => typeof name === 'string')));
593
- }
594
- return rulings;
595
- }
596
- /** A ruled object is accepted while no be/src source references it; a reference makes the ruling unproven. */
597
- function ruledObjectFinding(file, object, references) {
598
- const reference = references.find(({ scopes }) => referencesObject(scopes, object));
599
- return reference ? found(DB_DESTRUCTIVE_RULING_UNPROVEN, file, `${file}:${object.line} destroys ${object.name} under hfs.json db.destructiveRulings, but ${reference.file} still references it; the ruling holds only while its targets are unreferenced`, { line: object.line, object: object.name, reference: reference.file }) : null;
600
- }
601
- function destructiveFileFindings(file, text, references, ruled = new Set()) {
602
- const contract = CONTRACT_MIGRATION.test(file);
603
- const seen = new Set();
604
- const objects = migrationDestructiveObjects(text);
605
- const findings = objects.flatMap((object) => {
606
- const key = `${object.line}:${object.kind}:${object.name}`;
607
- if (seen.has(key))
608
- return [];
609
- seen.add(key);
610
- const finding = !contract && ruled.has(object.name) ? ruledObjectFinding(file, object, references) : destructiveObjectFinding(file, object, contract, references);
611
- return finding ? [finding] : [];
612
- });
613
- for (const name of ruled) {
614
- if (!objects.some((object) => object.name === name))
615
- findings.push(found(DB_DESTRUCTIVE_RULING_UNPROVEN, file, `hfs.json db.destructiveRulings names ${name} for ${file}, which the migration does not destroy; a ruling names exactly the objects its migration destroys`, { object: name }));
616
- }
617
- return findings;
618
- }
619
- const BE_SQL_SOURCE = /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/;
620
- /** The tag glob of a release (release.tagPrefix defaults to v). */
621
- const RELEASE_TAG_GLOB = 'v*';
622
- /**
623
- * A contract migration must not ship in the same release as the code change it depends on (cicd.md, Database migrations). The deploy applies
624
- * a contract migration right after the accept, while the release it replaced is still the rollback target: if that release's code still names
625
- * the destroyed object, a rollback after the contract would run code against a schema that no longer has it. The check judges exactly that
626
- * with git: each contract migration that is new since the previous release tag (absent there) is read for the objects it destroys, and the
627
- * be/src sources AS THEY WERE AT THE PREVIOUS RELEASE TAG must not reference them (the sources at HEAD are judged by destructiveMigrationFindings).
628
- * The first release, a repository without a release tag, or an unreadable git history has no previous release and no finding. It reports
629
- * DB_MIGRATION_DESTRUCTIVE (R259), a hard blocker: ship the code change in one release and its contract migration in the next.
630
- */
631
- export async function contractReleaseFindings({ repoRoot, migrations, git }) {
632
- const rulings = destructiveRulings(repoRoot);
633
- const contracts = migrations.filter((file) => CONTRACT_MIGRATION.test(file) || rulings.has(file));
634
- if (!contracts.length)
635
- return [];
636
- const previous = await runGit(git, repoRoot, ['previous-release', RELEASE_TAG_GLOB]);
637
- const release = previous.stdout.trim();
638
- if (!previous.ok || !release)
639
- return [];
640
- const known = new Set(await migrationFilesAt(git, repoRoot, release));
641
- const fresh = contracts.filter((file) => !known.has(file));
642
- if (!fresh.length)
643
- return [];
644
- const listing = await runGit(git, repoRoot, ['ls-tree', '-r', '--name-only', '-z', release, '--', 'be/src']);
645
- const sources = listing.ok ? listing.stdout.split('\0').filter((file) => BE_SQL_SOURCE.test(file)) : [];
646
- if (!sources.length)
647
- return [];
648
- const ts = loadTypescript(repoRoot, HERE);
649
- if (!ts)
650
- return [found(DB_MIGRATION_DESTRUCTIVE, 'hfs.json', 'the contract-release check requires the TypeScript parser to read the be/src references of the previous release')];
651
- const references = [];
652
- await eachInOrder(sources, async (file) => {
653
- references.push({ file, scopes: sourceNameScopes(ts, await baseFileText(git, repoRoot, release, file) ?? '', file) });
654
- });
655
- return fresh.flatMap((file) => {
656
- const text = readText(repoRoot, file);
657
- if (text === null)
658
- return [];
659
- // a ruled migration is judged here for its ruled objects only: its other objects are refused at HEAD already
660
- const ruled = CONTRACT_MIGRATION.test(file) ? undefined : rulings.get(file);
661
- return migrationDestructiveObjects(text).filter((object) => ruled === undefined || ruled.has(object.name)).flatMap((object) => {
662
- const reference = references.find(({ scopes }) => referencesObject(scopes, object));
663
- return reference ? [found(ruled === undefined ? DB_MIGRATION_DESTRUCTIVE : DB_DESTRUCTIVE_RULING_UNPROVEN, file, `${file}:${object.line} destroys ${object.name}, which the previous release ${release} still references in ${reference.file}; the contract migration runs right after the accept while that release is the rollback target: ship the code change in one release and this contract migration in the next`, { line: object.line, object: object.name, release, reference: reference.file })] : [];
664
- });
665
- });
666
- }
667
- /** Destructive changes require a contract migration and no remaining SQL/entity reference in be/src. */
668
- export function destructiveMigrationFindings({ repoRoot, migrations, files }) {
669
- const sources = files.filter((file) => /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/.test(file));
670
- const ts = sources.length ? loadTypescript(repoRoot, HERE) : null;
671
- if (sources.length && !ts)
672
- return [found(DB_MIGRATION_DESTRUCTIVE, 'hfs.json', 'destructive migration checks require the TypeScript parser to read be/src references')];
673
- const references = ts ? sources.map((file) => ({ file, scopes: sourceNameScopes(ts, readText(repoRoot, file) ?? '', file) })) : [];
674
- const rulings = destructiveRulings(repoRoot);
675
- const findings = migrations.flatMap((file) => {
676
- const text = readText(repoRoot, file);
677
- return text === null ? [] : destructiveFileFindings(file, text, references, rulings.get(file));
678
- });
679
- for (const migration of rulings.keys()) {
680
- if (!migrations.includes(migration))
681
- findings.push(found(DB_DESTRUCTIVE_RULING_UNPROVEN, 'hfs.json', `hfs.json db.destructiveRulings names ${migration}, which is no active migration; a ruling names the exact file it covers`, { migration }));
682
- }
683
- return findings;
684
- }