@astrale-os/sdk 0.6.0-beta.55 → 0.6.0-beta.57

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 (74) hide show
  1. package/README.md +11 -10
  2. package/dist/application/index.d.ts +2 -1
  3. package/dist/application/query/execution/crossings.d.ts +6 -1
  4. package/dist/application/query/execution/crossings.js +15 -1
  5. package/dist/application/query/execution/legacy/declared-classes.d.ts +10 -0
  6. package/dist/application/query/execution/legacy/declared-classes.js +9 -0
  7. package/dist/application/requirements/canonical.d.ts +7 -0
  8. package/dist/application/requirements/canonical.js +16 -0
  9. package/dist/application/requirements/classes.d.ts +9 -7
  10. package/dist/application/requirements/classes.js +35 -42
  11. package/dist/application/requirements/functions.d.ts +3 -1
  12. package/dist/application/requirements/functions.js +12 -27
  13. package/dist/application/requirements/index.d.ts +34 -16
  14. package/dist/application/requirements/index.js +17 -20
  15. package/dist/application/requirements/legacy/authority.d.ts +21 -0
  16. package/dist/application/requirements/{authority.js → legacy/authority.js} +5 -2
  17. package/dist/application/requirements/legacy/classes.d.ts +22 -0
  18. package/dist/application/requirements/legacy/classes.js +24 -0
  19. package/dist/application/requirements/legacy/core.d.ts +30 -0
  20. package/dist/application/requirements/{core.js → legacy/core.js} +15 -13
  21. package/dist/application/requirements/legacy/functions.d.ts +7 -0
  22. package/dist/application/requirements/legacy/functions.js +15 -0
  23. package/dist/application/requirements/legacy/index.d.ts +43 -0
  24. package/dist/application/requirements/legacy/index.js +1 -0
  25. package/dist/application/requirements/legacy/requirements.d.ts +31 -0
  26. package/dist/application/requirements/legacy/requirements.js +31 -0
  27. package/dist/application/requirements/requirement.d.ts +30 -19
  28. package/dist/application/requirements/roles.d.ts +17 -0
  29. package/dist/application/requirements/roles.js +62 -0
  30. package/dist/application/requirements/scopes.d.ts +16 -0
  31. package/dist/application/requirements/scopes.js +34 -0
  32. package/dist/deployment/build/build.d.ts +3 -5
  33. package/dist/deployment/build/compile.js +12 -64
  34. package/dist/deployment/build/legacy/requirements.d.ts +11 -0
  35. package/dist/deployment/build/legacy/requirements.js +79 -0
  36. package/dist/deployment/build/material.js +0 -3
  37. package/dist/execution/invocation/dispatch/context.js +2 -1
  38. package/dist/platform/schema/class-authoring.d.ts +9 -7
  39. package/dist/platform/schema/class-authoring.js +3 -2
  40. package/dist/platform/schema/index.d.ts +1 -1
  41. package/dist/testing/query.js +2 -1
  42. package/dist/tooling/linter/adapters/typescript/discover.js +8 -2
  43. package/dist/tooling/linter/adapters/typescript/index.d.ts +6 -0
  44. package/dist/tooling/linter/adapters/typescript/index.js +1 -0
  45. package/dist/tooling/linter/adapters/typescript/legacy.d.ts +20 -0
  46. package/dist/tooling/linter/adapters/typescript/legacy.js +28 -0
  47. package/dist/tooling/linter/implementations/source/callable-requirements.d.ts +1 -2
  48. package/dist/tooling/linter/implementations/source/callable-requirements.js +7 -44
  49. package/dist/tooling/linter/implementations/source/const-initializer.d.ts +3 -0
  50. package/dist/tooling/linter/implementations/source/const-initializer.js +31 -0
  51. package/dist/tooling/linter/implementations/source/domain-requirements.d.ts +8 -0
  52. package/dist/tooling/linter/implementations/source/domain-requirements.js +35 -0
  53. package/dist/tooling/linter/implementations/source/global.js +21 -8
  54. package/dist/tooling/linter/implementations/source/legacy/requirements.d.ts +10 -0
  55. package/dist/tooling/linter/implementations/source/legacy/requirements.js +40 -0
  56. package/dist/tooling/linter/implementations/source/legacy-folders.d.ts +3 -0
  57. package/dist/tooling/linter/implementations/source/legacy-folders.js +126 -0
  58. package/dist/tooling/linter/implementations/source/mutations.js +7 -22
  59. package/dist/tooling/linter/implementations/source/requirement-entries.d.ts +24 -0
  60. package/dist/tooling/linter/implementations/source/requirement-entries.js +52 -0
  61. package/dist/tooling/linter/implementations/source/schema.d.ts +3 -0
  62. package/dist/tooling/linter/implementations/source/schema.js +9 -5
  63. package/dist/tooling/linter/implementations/source/tests.js +1 -1
  64. package/dist/tooling/linter/implementations/source/verifiers.js +2 -0
  65. package/dist/tooling/linter/policy/generated.js +2 -2
  66. package/dist/tooling/linter/requirements/registry.js +2 -0
  67. package/docs/accounts/scenarios.tsv +12 -0
  68. package/docs/handler-dependencies.md +5 -3
  69. package/docs/legacy.md +113 -0
  70. package/docs/queries.md +3 -2
  71. package/docs/requirements.md +134 -0
  72. package/package.json +4 -4
  73. package/dist/application/requirements/authority.d.ts +0 -7
  74. package/dist/application/requirements/core.d.ts +0 -14
@@ -4,6 +4,7 @@ import { dirname, extname, join, relative, resolve } from 'node:path';
4
4
  import ts from 'typescript';
5
5
  import { LinterToolError } from '../../diagnostics/index.js';
6
6
  import { collectDependencyIssues, collectImports } from './imports.js';
7
+ import { governedPath, legacyPlacement } from './legacy.js';
7
8
  const IGNORED = new Set([
8
9
  '.astrale',
9
10
  '.dist',
@@ -209,13 +210,18 @@ async function admitFile(root, absolutePath, policy) {
209
210
  });
210
211
  }
211
212
  const source = ts.createSourceFile(absolutePath, text, ts.ScriptTarget.Latest, true, scriptKind(absolutePath));
212
- const layer = policy.layers.find(({ sourcePath }) => path.startsWith(sourcePath));
213
- const remainder = layer ? path.slice(layer.sourcePath.length) : undefined;
213
+ // A legacy/ folder is transparent: the file belongs to the layer and submodule of its owner.
214
+ const governed = governedPath(path);
215
+ const legacy = legacyPlacement(path);
216
+ const layer = policy.layers.find(({ sourcePath }) => governed.startsWith(sourcePath));
217
+ const remainder = layer ? governed.slice(layer.sourcePath.length) : undefined;
214
218
  const submodule = semanticSubmodule(layer?.id, remainder);
215
219
  const role = sourceRole(path, layer?.id);
216
220
  return Object.freeze({
217
221
  absolutePath,
218
222
  path,
223
+ governedPath: governed,
224
+ ...(legacy ? { legacy } : {}),
219
225
  text,
220
226
  source,
221
227
  role,
@@ -8,8 +8,10 @@ export { queryCollectionKind } from './query-collection-type.js';
8
8
  export { isDefinitionFactory, definitionCalls, type DefinitionCall, type DefinitionFactory, } from './definition-calls.js';
9
9
  export { declarationOf, expressionType, type ExpressionType } from './type-analysis.js';
10
10
  export { collectSuppressionDirectives } from './suppression-directives.js';
11
+ export { governedPath, legacyPlacement, type LegacyPlacement } from './legacy.js';
11
12
  import type ts from 'typescript';
12
13
  import type { DomainPolicy } from '../../policy/index.js';
14
+ import type { LegacyPlacement } from './legacy.js';
13
15
  export type SourceRole = 'production' | 'focused-test' | 'system-test';
14
16
  export interface SourceImport {
15
17
  readonly specifier: string;
@@ -26,6 +28,10 @@ export interface SourceDependencyIssue {
26
28
  export interface SourceFile {
27
29
  readonly absolutePath: string;
28
30
  readonly path: string;
31
+ /** The path its owner's structure classifies: each `legacy/` directory removed (MOD-LEGACY). */
32
+ readonly governedPath: string;
33
+ /** Where the file sits in a `legacy/` folder, when it does. */
34
+ readonly legacy?: LegacyPlacement;
29
35
  readonly text: string;
30
36
  readonly source: ts.SourceFile;
31
37
  readonly role: SourceRole;
@@ -8,3 +8,4 @@ export { queryCollectionKind } from './query-collection-type.js';
8
8
  export { isDefinitionFactory, definitionCalls, } from './definition-calls.js';
9
9
  export { declarationOf, expressionType } from './type-analysis.js';
10
10
  export { collectSuppressionDirectives } from './suppression-directives.js';
11
+ export { governedPath, legacyPlacement } from './legacy.js';
@@ -0,0 +1,20 @@
1
+ /**
2
+ * A `legacy/` folder (docs/legacy.md, MOD-LEGACY) keeps old behaviour beside the owner it serves.
3
+ * It is transparent to the owner's structure: a file in it is classified as if the `legacy/`
4
+ * directory were absent, so a legacy Policy is still a Policy leaf and a legacy module facade is
5
+ * still that module's facade.
6
+ */
7
+ export interface LegacyPlacement {
8
+ /** The owner the folder serves, as a path prefix: `''` for the Domain root, else ending in `/`. */
9
+ readonly owner: string;
10
+ /** The folder itself: `<owner>legacy/`. */
11
+ readonly folder: string;
12
+ /** The folder's own `index` facade, which the owner's seam imports. */
13
+ readonly facade: boolean;
14
+ /** A file directly in the folder, other than its facade, named for what it keeps. */
15
+ readonly keeper: boolean;
16
+ }
17
+ /** The path as its owner's structure reads it: every `legacy/` directory removed. */
18
+ export declare function governedPath(path: string): string;
19
+ /** Where a file sits in its outermost `legacy/` folder, or `undefined` outside every one. */
20
+ export declare function legacyPlacement(path: string): LegacyPlacement | undefined;
@@ -0,0 +1,28 @@
1
+ const LEGACY = 'legacy';
2
+ const INDEX = /^index\.[cm]?[jt]sx?$/u;
3
+ /** The path as its owner's structure reads it: every `legacy/` directory removed. */
4
+ export function governedPath(path) {
5
+ const segments = path.split('/');
6
+ return segments
7
+ .filter((segment, index) => index === segments.length - 1 || segment !== LEGACY)
8
+ .join('/');
9
+ }
10
+ /** Where a file sits in its outermost `legacy/` folder, or `undefined` outside every one. */
11
+ export function legacyPlacement(path) {
12
+ const segments = path.split('/');
13
+ const position = segments.slice(0, -1).indexOf(LEGACY);
14
+ if (position < 0)
15
+ return undefined;
16
+ const owner = segments
17
+ .slice(0, position)
18
+ .map((segment) => `${segment}/`)
19
+ .join('');
20
+ const rest = segments.slice(position + 1);
21
+ const direct = rest.length === 1;
22
+ return Object.freeze({
23
+ owner,
24
+ folder: `${owner}${LEGACY}/`,
25
+ facade: direct && INDEX.test(rest[0]),
26
+ keeper: direct && !INDEX.test(rest[0]),
27
+ });
28
+ }
@@ -1,5 +1,6 @@
1
1
  import ts from 'typescript';
2
2
  import { type SourceFile, type SourceProject } from '../../adapters/typescript/index.js';
3
+ export { lexicalConstInitializer } from './const-initializer.js';
3
4
  export interface RemoteCallable {
4
5
  readonly file: SourceFile;
5
6
  readonly node: ts.CallExpression;
@@ -23,5 +24,3 @@ export declare function callableReference(expression: ts.Expression): {
23
24
  readonly expression: ts.Expression;
24
25
  readonly resolved: boolean;
25
26
  };
26
- /** Resolve only one immutable lexical alias; the linter does not emulate program execution. */
27
- export declare function lexicalConstInitializer(identifier: ts.Identifier): ts.Expression | undefined;
@@ -1,6 +1,9 @@
1
1
  import ts from 'typescript';
2
- import { bindingContains, objectProperty, resolveImportedSymbol, resolveProjectImport, unwrap, visit, } from '../../adapters/typescript/index.js';
2
+ import { objectProperty, resolveImportedSymbol, resolveProjectImport, unwrap, visit, } from '../../adapters/typescript/index.js';
3
+ import { lexicalConstInitializer } from './const-initializer.js';
4
+ import { requirementEntries } from './domain-requirements.js';
3
5
  import { definitionObjects, DSL_MODULES, production, propertyExpression } from './shared.js';
6
+ export { lexicalConstInitializer } from './const-initializer.js';
4
7
  export function domainFunctionRequirements(project) {
5
8
  const domainPath = project.policy.rootFiles.find(({ id }) => id === 'domain')?.sourcePath;
6
9
  const file = domainPath && project.filesByPath.get(domainPath);
@@ -49,21 +52,10 @@ export function domainFunctionRequirements(project) {
49
52
  if (!ts.isObjectLiteralExpression(unwrap(definition))) {
50
53
  return { keys: new Set(), indeterminate: true };
51
54
  }
52
- const functions = objectProperty(unwrap(definition), 'functions');
53
- if (functions === undefined)
54
- return { keys: new Set(), indeterminate: false };
55
- if (!ts.isPropertyAssignment(functions))
56
- return { keys: new Set(), indeterminate: true };
57
- const values = unwrap(functions.initializer);
58
- if (!ts.isArrayLiteralExpression(values))
59
- return { keys: new Set(), indeterminate: true };
55
+ const entries = requirementEntries(unwrap(definition));
60
56
  const keys = new Set();
61
- let indeterminate = false;
62
- for (const element of values.elements) {
63
- if (ts.isSpreadElement(element)) {
64
- indeterminate = true;
65
- continue;
66
- }
57
+ let indeterminate = entries.indeterminate;
58
+ for (const element of entries.callables) {
67
59
  const target = requiredCallable(project, file, element);
68
60
  if (target === undefined)
69
61
  indeterminate = true;
@@ -198,32 +190,3 @@ export function callableReference(expression) {
198
190
  ? { expression, resolved: false }
199
191
  : { expression: unwrap(initializer), resolved: true };
200
192
  }
201
- /** Resolve only one immutable lexical alias; the linter does not emulate program execution. */
202
- export function lexicalConstInitializer(identifier) {
203
- let child = identifier;
204
- let current = identifier.parent;
205
- while (current) {
206
- if (ts.isFunctionLike(current)) {
207
- if (current.parameters.some(({ name }) => bindingContains(name, identifier.text))) {
208
- return undefined;
209
- }
210
- }
211
- if (ts.isBlock(current) || ts.isSourceFile(current) || ts.isModuleBlock(current)) {
212
- const index = current.statements.findIndex((statement) => statement.pos <= child.pos && statement.end >= child.end);
213
- const before = index < 0 ? current.statements : current.statements.slice(0, index);
214
- for (const statement of [...before].reverse()) {
215
- if (!ts.isVariableStatement(statement))
216
- continue;
217
- const declaration = statement.declarationList.declarations.find(({ name }) => ts.isIdentifier(name) && name.text === identifier.text);
218
- if (!declaration)
219
- continue;
220
- return (statement.declarationList.flags & ts.NodeFlags.Const) !== 0
221
- ? declaration.initializer
222
- : undefined;
223
- }
224
- }
225
- child = current;
226
- current = current.parent;
227
- }
228
- return undefined;
229
- }
@@ -0,0 +1,3 @@
1
+ import ts from 'typescript';
2
+ /** Resolve only one immutable lexical alias; the linter does not emulate program execution. */
3
+ export declare function lexicalConstInitializer(identifier: ts.Identifier): ts.Expression | undefined;
@@ -0,0 +1,31 @@
1
+ import ts from 'typescript';
2
+ import { bindingContains } from '../../adapters/typescript/index.js';
3
+ /** Resolve only one immutable lexical alias; the linter does not emulate program execution. */
4
+ export function lexicalConstInitializer(identifier) {
5
+ let child = identifier;
6
+ let current = identifier.parent;
7
+ while (current) {
8
+ if (ts.isFunctionLike(current)) {
9
+ if (current.parameters.some(({ name }) => bindingContains(name, identifier.text))) {
10
+ return undefined;
11
+ }
12
+ }
13
+ if (ts.isBlock(current) || ts.isSourceFile(current) || ts.isModuleBlock(current)) {
14
+ const index = current.statements.findIndex((statement) => statement.pos <= child.pos && statement.end >= child.end);
15
+ const before = index < 0 ? current.statements : current.statements.slice(0, index);
16
+ for (const statement of [...before].reverse()) {
17
+ if (!ts.isVariableStatement(statement))
18
+ continue;
19
+ const declaration = statement.declarationList.declarations.find(({ name }) => ts.isIdentifier(name) && name.text === identifier.text);
20
+ if (!declaration)
21
+ continue;
22
+ return (statement.declarationList.flags & ts.NodeFlags.Const) !== 0
23
+ ? declaration.initializer
24
+ : undefined;
25
+ }
26
+ }
27
+ child = current;
28
+ current = current.parent;
29
+ }
30
+ return undefined;
31
+ }
@@ -0,0 +1,8 @@
1
+ import type ts from 'typescript';
2
+ import type { RequirementEntries } from './requirement-entries.js';
3
+ /**
4
+ * Read a static `requirements({ roles, scopes })` object: a scope with `call` lets the Domain call
5
+ * its target; any other scope holds Class operations. Roles grant no callable or Class by name, so
6
+ * no rule reads them.
7
+ */
8
+ export declare function requirementEntries(definition: ts.ObjectLiteralExpression): RequirementEntries;
@@ -0,0 +1,35 @@
1
+ import { legacyRequirementEntries } from './legacy/requirements.js';
2
+ import { arrayElements, assigned, entryObject, operationNames } from './requirement-entries.js';
3
+ /**
4
+ * Read a static `requirements({ roles, scopes })` object: a scope with `call` lets the Domain call
5
+ * its target; any other scope holds Class operations. Roles grant no callable or Class by name, so
6
+ * no rule reads them.
7
+ */
8
+ export function requirementEntries(definition) {
9
+ // The one seam to the legacy shape: it answers only when a key only that shape declares is set.
10
+ const legacy = legacyRequirementEntries(definition);
11
+ if (legacy !== undefined)
12
+ return legacy;
13
+ const scopes = arrayElements(definition, 'scopes');
14
+ if (scopes === 'opaque')
15
+ return { callables: [], classes: [], indeterminate: true };
16
+ const callables = [];
17
+ const classes = [];
18
+ let indeterminate = false;
19
+ for (const element of scopes ?? []) {
20
+ const scope = entryObject(element);
21
+ const on = scope && assigned(scope, 'on');
22
+ const operations = scope && assigned(scope, 'operations');
23
+ const names = operations && operationNames(operations);
24
+ if (on === undefined || operations === undefined || names === undefined) {
25
+ indeterminate = true;
26
+ }
27
+ else if (names.includes('call')) {
28
+ callables.push(on);
29
+ }
30
+ else {
31
+ classes.push({ target: on, operations });
32
+ }
33
+ }
34
+ return { callables, classes, indeterminate };
35
+ }
@@ -85,7 +85,8 @@ export const globalRules = [
85
85
  evaluate(project) {
86
86
  const governedRoots = new Set(project.policy.rootFiles.map(({ sourcePath }) => sourcePath));
87
87
  return production(project).flatMap((file) => {
88
- if (file.layer || governedRoots.has(file.path))
88
+ // The Domain root's own legacy/ folder is a governed root too (MOD-LEGACY).
89
+ if (file.layer || governedRoots.has(file.path) || file.legacy?.owner === '')
89
90
  return [];
90
91
  const evidence = `Production source ${file.path} is outside every declared layer and governed root. Move Domain source into a declared layer; exclude a directory that is not Domain source, such as mockups, with an "ignore" glob in astrale.lint.json.`;
91
92
  const anchor = file.source.statements[0];
@@ -102,8 +103,10 @@ export const globalRules = [
102
103
  if (!file.layer || file.submodule || isLayerFacadeFile(project, file))
103
104
  continue;
104
105
  const layer = project.policy.layers.find(({ id }) => id === file.layer);
105
- const relative = layer ? file.path.slice(layer.sourcePath.length) : file.path;
106
- if (relative !== 'index.ts' && relative !== 'index.tsx') {
106
+ const relative = layer ? file.governedPath.slice(layer.sourcePath.length) : file.path;
107
+ // Of layer roots, only the Schema root owns a legacy/ folder, which may hold keepers.
108
+ const schemaKeeper = file.layer === 'schema' && file.legacy?.keeper === true;
109
+ if (relative !== 'index.ts' && relative !== 'index.tsx' && !schemaKeeper) {
107
110
  evidence.push(violation(file, file.source, `Layer-root source ${file.path} has no semantic submodule owner.`));
108
111
  }
109
112
  }
@@ -119,7 +122,7 @@ export const globalRules = [
119
122
  if (!file.layer || file.submodule)
120
123
  continue;
121
124
  const layer = project.policy.layers.find(({ id }) => id === file.layer);
122
- const relative = layer ? file.path.slice(layer.sourcePath.length) : file.path;
125
+ const relative = layer ? file.governedPath.slice(layer.sourcePath.length) : file.path;
123
126
  if (relative !== 'index.ts' && relative !== 'index.tsx')
124
127
  continue;
125
128
  const facadeNames = layerFacadeNames(project, file);
@@ -143,7 +146,9 @@ export const globalRules = [
143
146
  : violation(file, statement, `Layer index re-exports external package ${statement.moduleSpecifier.text}.`));
144
147
  }
145
148
  else if (target.layer !== file.layer ||
146
- (!target.submodule && !isLayerFacadeFile(project, target))) {
149
+ (!target.submodule &&
150
+ !isLayerFacadeFile(project, target) &&
151
+ !isOwnLegacyKeeper(file, target))) {
147
152
  evidence.push(violation(file, statement, `Layer index export targets non-submodule source ${target.path}.`));
148
153
  }
149
154
  else if (target.submodule &&
@@ -167,7 +172,9 @@ export const globalRules = [
167
172
  : violation(file, element, `Layer index exports external package ${sourceImport.specifier}.`));
168
173
  }
169
174
  else if (target.layer !== file.layer ||
170
- (!target.submodule && !isLayerFacadeFile(project, target))) {
175
+ (!target.submodule &&
176
+ !isLayerFacadeFile(project, target) &&
177
+ !isOwnLegacyKeeper(file, target))) {
171
178
  evidence.push(violation(file, element, `Layer index export targets non-submodule source ${target.path}.`));
172
179
  }
173
180
  else if (target.submodule &&
@@ -363,7 +370,7 @@ export const globalRules = [
363
370
  continue;
364
371
  }
365
372
  const facade = `${target.layer}/${target.submodule}/index.`;
366
- if (!target.path.startsWith(facade)) {
373
+ if (!target.governedPath.startsWith(facade)) {
367
374
  evidence.push(violation(file, sourceImport.node, `Import ${sourceImport.specifier} reaches private ${target.path}; use ${target.layer}/${target.submodule}/index.ts.`));
368
375
  }
369
376
  }
@@ -930,7 +937,13 @@ function layerFacadePath(project, layerId) {
930
937
  return layer?.facade === undefined ? undefined : `${layer.sourcePath}${layer.facade}`;
931
938
  }
932
939
  function isLayerFacadeFile(project, file) {
933
- return file.layer !== undefined && layerFacadePath(project, file.layer) === file.path;
940
+ return file.layer !== undefined && layerFacadePath(project, file.layer) === file.governedPath;
941
+ }
942
+ /** A legacy folder's facade may expose the flat keepers of its own folder (MOD-LEGACY). */
943
+ function isOwnLegacyKeeper(facade, target) {
944
+ return (facade.legacy?.facade === true &&
945
+ target.legacy?.keeper === true &&
946
+ target.legacy.folder === facade.legacy.folder);
934
947
  }
935
948
  function submoduleOwnsLayerFacade(project, layerId, submodule) {
936
949
  if (layerFacadePath(project, layerId) === undefined)
@@ -0,0 +1,10 @@
1
+ import ts from 'typescript';
2
+ import type { RequirementEntries } from '../requirement-entries.js';
3
+ /**
4
+ * @deprecated Read the legacy `functions` and `classes` of a static requirements object as the
5
+ * callables and Classes a rule matches (L-SDK-4); `undefined` when the object declares no legacy
6
+ * key. Replaced by the `scopes` reading of `requirementEntries`. Removal: in the SDK major that
7
+ * adopts a Kernel cohort no longer admitting the legacy capability shape (Kernel
8
+ * `LegacyCapabilityRequirements`, A1e).
9
+ */
10
+ export declare function legacyRequirementEntries(definition: ts.ObjectLiteralExpression): RequirementEntries | undefined;
@@ -0,0 +1,40 @@
1
+ import ts from 'typescript';
2
+ import { objectProperty } from '../../../adapters/typescript/index.js';
3
+ import { arrayElements, assigned, entryObject } from '../requirement-entries.js';
4
+ const LEGACY_KEYS = ['functions', 'classes', 'authority', 'core'];
5
+ /**
6
+ * @deprecated Read the legacy `functions` and `classes` of a static requirements object as the
7
+ * callables and Classes a rule matches (L-SDK-4); `undefined` when the object declares no legacy
8
+ * key. Replaced by the `scopes` reading of `requirementEntries`. Removal: in the SDK major that
9
+ * adopts a Kernel cohort no longer admitting the legacy capability shape (Kernel
10
+ * `LegacyCapabilityRequirements`, A1e).
11
+ */
12
+ export function legacyRequirementEntries(definition) {
13
+ if (!LEGACY_KEYS.some((key) => objectProperty(definition, key) !== undefined))
14
+ return undefined;
15
+ let indeterminate = false;
16
+ const functions = arrayElements(definition, 'functions');
17
+ if (functions === 'opaque')
18
+ indeterminate = true;
19
+ const callables = [];
20
+ for (const element of functions === 'opaque' ? [] : (functions ?? [])) {
21
+ if (ts.isSpreadElement(element))
22
+ indeterminate = true;
23
+ else
24
+ callables.push(element);
25
+ }
26
+ const classList = arrayElements(definition, 'classes');
27
+ if (classList === 'opaque')
28
+ indeterminate = true;
29
+ const classes = [];
30
+ for (const element of classList === 'opaque' ? [] : (classList ?? [])) {
31
+ const entry = entryObject(element);
32
+ const target = entry && assigned(entry, 'class');
33
+ const operations = entry && assigned(entry, 'operations');
34
+ if (target === undefined || operations === undefined)
35
+ indeterminate = true;
36
+ else
37
+ classes.push({ target, operations });
38
+ }
39
+ return { callables, classes, indeterminate };
40
+ }
@@ -0,0 +1,3 @@
1
+ import type { SourceRuleVerifier } from './verifier.js';
2
+ /** The legacy method (docs/legacy.md) applied to Domain source. */
3
+ export declare const legacyFolderRules: readonly SourceRuleVerifier[];
@@ -0,0 +1,126 @@
1
+ import ts from 'typescript';
2
+ import { resolveProjectImport, } from '../../adapters/typescript/index.js';
3
+ import { locallyConstructedDeclarations } from './schema.js';
4
+ import { production, violation } from './shared.js';
5
+ const LEGACY_NAME = /^(?:legacy|Legacy|LEGACY_)/u;
6
+ // `L-<REPO>-<n>`, or `L-<REPO>-<P><n>` for one package's own ledger in a repository with several.
7
+ const LEDGER_ID = /\(L-[A-Z0-9]+-[A-Z]?\d+\)/u;
8
+ /** The legacy method (docs/legacy.md) applied to Domain source. */
9
+ export const legacyFolderRules = [
10
+ {
11
+ id: 'MOD-LEGACY',
12
+ ruleRevision: '2b52d972658c63586871ed99f4eac33d663921605ecc6c56679f4999bcfb5dd0',
13
+ evaluate(project) {
14
+ const evidence = [];
15
+ for (const file of project.files) {
16
+ const placement = file.legacy;
17
+ if (placement === undefined)
18
+ continue;
19
+ const inside = file.path.slice(placement.folder.length).split('/').slice(0, -1);
20
+ if (inside.includes('legacy')) {
21
+ evidence.push(violation(file, file.source, `Legacy source ${file.path} nests a legacy/ folder inside ${placement.folder}; keep one legacy/ folder beside its owner.`));
22
+ continue;
23
+ }
24
+ if (file.role !== 'production' || !placement.keeper || !flatSchemaKeeper(project, file)) {
25
+ continue;
26
+ }
27
+ const declaration = locallyConstructedDeclarations(file)[0];
28
+ if (declaration !== undefined) {
29
+ evidence.push(violation(file, declaration, `Legacy keeper ${file.path} constructs a Schema declaration; declare it in its declaration-kind directory under ${placement.folder}, as its owner would.`));
30
+ }
31
+ }
32
+ for (const file of production(project)) {
33
+ // Legacy code may reach any legacy code; target code reaches it only through its seam.
34
+ if (file.legacy !== undefined)
35
+ continue;
36
+ for (const sourceImport of file.imports) {
37
+ const target = resolveProjectImport(project, file, sourceImport.specifier);
38
+ const placement = target?.legacy;
39
+ if (target === undefined || placement === undefined)
40
+ continue;
41
+ if (!placement.facade) {
42
+ evidence.push(violation(file, sourceImport.node, `Import ${sourceImport.specifier} reaches ${target.path} past its legacy facade; import ${placement.folder}index.ts.`));
43
+ }
44
+ else if (!file.path.startsWith(placement.owner)) {
45
+ evidence.push(violation(file, sourceImport.node, `Import ${sourceImport.specifier} reaches the legacy facade ${target.path} from outside its owner ${placement.owner}; only that owner's seam or other legacy code imports it.`));
46
+ }
47
+ }
48
+ }
49
+ return evidence;
50
+ },
51
+ },
52
+ {
53
+ id: 'QLT-LEGACY-TAG',
54
+ ruleRevision: '14569883eff894becf3720adc2bfa6349f393fce815cd12ea059023933f13626',
55
+ evaluate(project) {
56
+ const evidence = [];
57
+ for (const file of production(project)) {
58
+ if (file.legacy === undefined)
59
+ continue;
60
+ for (const statement of file.source.statements) {
61
+ for (const { name, node } of exportedDeclarations(statement)) {
62
+ if (!LEGACY_NAME.test(name)) {
63
+ evidence.push(violation(file, node, `Legacy export ${name} of ${file.path} is not named legacy…, Legacy…, or LEGACY_….`));
64
+ }
65
+ const doc = deprecation(file, statement);
66
+ if (doc === undefined ||
67
+ !LEDGER_ID.test(doc) ||
68
+ !doc.includes('Replaced by') ||
69
+ !doc.includes('Removal:')) {
70
+ evidence.push(violation(file, node, `Legacy export ${name} of ${file.path} needs @deprecated <what it keeps> (<ledger id>). Replaced by <target>. Removal: <condition>.`));
71
+ }
72
+ }
73
+ }
74
+ }
75
+ return evidence;
76
+ },
77
+ },
78
+ ];
79
+ /**
80
+ * A keeper file where its Schema owner admits only a facade: the Schema root or a Schema module.
81
+ * Its declarations belong to the kind directories its owner would hold them in.
82
+ */
83
+ function flatSchemaKeeper(project, file) {
84
+ const layer = project.policy.layers.find(({ id }) => id === 'schema');
85
+ if (layer === undefined || file.layer !== 'schema')
86
+ return false;
87
+ const segments = file.governedPath.slice(layer.sourcePath.length).split('/');
88
+ return segments.length === 1 || (segments[0] === 'modules' && segments.length === 3);
89
+ }
90
+ /** The names a statement exports as its own declarations; re-exports belong to their source. */
91
+ function exportedDeclarations(statement) {
92
+ if (ts.isExportAssignment(statement))
93
+ return [{ name: 'default', node: statement }];
94
+ const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
95
+ if (!modifiers?.some(({ kind }) => kind === ts.SyntaxKind.ExportKeyword))
96
+ return [];
97
+ if (modifiers.some(({ kind }) => kind === ts.SyntaxKind.DefaultKeyword)) {
98
+ return [{ name: 'default', node: statement }];
99
+ }
100
+ if (ts.isVariableStatement(statement)) {
101
+ return statement.declarationList.declarations.map((declaration) => ({
102
+ name: ts.isIdentifier(declaration.name) ? declaration.name.text : declaration.name.getText(),
103
+ node: declaration.name,
104
+ }));
105
+ }
106
+ if ((ts.isFunctionDeclaration(statement) ||
107
+ ts.isClassDeclaration(statement) ||
108
+ ts.isInterfaceDeclaration(statement) ||
109
+ ts.isTypeAliasDeclaration(statement) ||
110
+ ts.isEnumDeclaration(statement) ||
111
+ ts.isModuleDeclaration(statement)) &&
112
+ statement.name !== undefined) {
113
+ return [{ name: statement.name.text, node: statement.name }];
114
+ }
115
+ return [];
116
+ }
117
+ /** The `@deprecated` text of the JSDoc right above a statement, its lines joined. */
118
+ function deprecation(file, statement) {
119
+ const comment = (ts.getLeadingCommentRanges(file.text, statement.getFullStart()) ?? [])
120
+ .map(({ pos, end }) => file.text.slice(pos, end))
121
+ .filter((text) => text.startsWith('/**'))
122
+ .at(-1);
123
+ const text = comment?.replace(/\s*\n\s*\*?\s?/gu, ' ');
124
+ const start = text?.indexOf('@deprecated');
125
+ return text === undefined || start === undefined || start < 0 ? undefined : text.slice(start);
126
+ }
@@ -1,6 +1,7 @@
1
1
  import ts from 'typescript';
2
2
  import { isLocalAlias } from '../../../../platform/graph/alias.js';
3
3
  import { expressionType, importedSymbol, propertyChain, staticText, unwrap, visit, visitOwnBody, } from '../../adapters/typescript/index.js';
4
+ import { requirementEntries } from './domain-requirements.js';
4
5
  import { ambiguity, callback, calls, DSL_MODULES, definitionOriginAmbiguity, definitionObjects, domainProjectorEvidence, forbiddenIoImport, hasForbiddenGlobalCall, production, violation, } from './shared.js';
5
6
  import { stateMachineIdentity, statePropertyIdentity } from './state-machine.js';
6
7
  const FORBIDDEN_LAYERS = new Set(['integrations', 'functions', 'providers', 'queries']);
@@ -885,36 +886,20 @@ function domainPlanRequirements(project) {
885
886
  const definition = staticObject(requirementCall.arguments[0]);
886
887
  if (!definition)
887
888
  return emptyPlanRequirements(requirementCall.arguments[0] !== undefined);
889
+ const entries = requirementEntries(definition);
888
890
  const functions = new Set();
889
891
  const classes = new Set();
890
- let indeterminate = false;
891
- const functionValues = staticArray(assignedValue(definition, 'functions'));
892
- if (assignedValue(definition, 'functions') !== undefined && !functionValues)
893
- indeterminate = true;
894
- for (const value of functionValues?.elements ?? []) {
895
- if (!ts.isExpression(value)) {
896
- indeterminate = true;
897
- continue;
898
- }
892
+ let indeterminate = entries.indeterminate;
893
+ for (const value of entries.callables) {
899
894
  const chain = staticPropertyChain(value);
900
895
  if (chain?.at(-2) !== 'functions' || chain.at(-1) === undefined)
901
896
  indeterminate = true;
902
897
  else
903
898
  functions.add(chain.at(-1));
904
899
  }
905
- const classValues = staticArray(assignedValue(definition, 'classes'));
906
- if (assignedValue(definition, 'classes') !== undefined && !classValues)
907
- indeterminate = true;
908
- for (const value of classValues?.elements ?? []) {
909
- if (!ts.isExpression(value)) {
910
- indeterminate = true;
911
- continue;
912
- }
913
- const object = staticObject(value);
914
- const selected = object && assignedValue(object, 'class');
915
- const target = selected && resolvedDependencyClassTarget(file, selected);
916
- const operationValue = object && assignedValue(object, 'operations');
917
- const operations = operationValue && staticStringArray(operationValue);
900
+ for (const entry of entries.classes) {
901
+ const target = resolvedDependencyClassTarget(file, entry.target);
902
+ const operations = staticStringArray(entry.operations);
918
903
  if (!target || !operations || operations.length === 0) {
919
904
  indeterminate = true;
920
905
  continue;
@@ -0,0 +1,24 @@
1
+ import ts from 'typescript';
2
+ /** A Class requirement as written: the expression naming its Class, and its operations. */
3
+ export interface ClassRequirementEntry {
4
+ readonly target: ts.Expression;
5
+ readonly operations: ts.Expression;
6
+ }
7
+ /** What a static `requirements({ ... })` object lets the Domain call and do on Classes. */
8
+ export interface RequirementEntries {
9
+ /** The expressions naming each callable the Domain may call. */
10
+ readonly callables: readonly ts.Expression[];
11
+ /** The Classes the Domain holds operations on. */
12
+ readonly classes: readonly ClassRequirementEntry[];
13
+ /** Some entry could not be read without executing the program. */
14
+ readonly indeterminate: boolean;
15
+ }
16
+ export declare const NO_REQUIREMENT_ENTRIES: RequirementEntries;
17
+ /** The elements of an array property; `undefined` when absent, `opaque` when not a literal. */
18
+ export declare function arrayElements(object: ts.ObjectLiteralExpression, name: string): readonly ts.Expression[] | undefined | 'opaque';
19
+ /** One object entry of a requirement list, through one immutable lexical alias at most. */
20
+ export declare function entryObject(expression: ts.Expression): ts.ObjectLiteralExpression | undefined;
21
+ /** The value a static object assigns to a property. */
22
+ export declare function assigned(object: ts.ObjectLiteralExpression, name: string): ts.Expression | undefined;
23
+ /** The string literals of a static array, or `undefined` when any is not one. */
24
+ export declare function operationNames(expression: ts.Expression): readonly string[] | undefined;