@domain-first/project-structure 8.4.0 → 8.5.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.
- package/README.md +4 -3
- package/dist/38.js +23 -11
- package/dist/870.js +2 -1
- package/dist/agent-cli.d.ts +1 -1
- package/dist/config-file.d.ts +4 -1
- package/dist/graph.cjs +2 -1
- package/dist/index.cjs +2 -1
- package/dist/init.cjs +2 -1
- package/dist/integration.cjs +2 -1
- package/dist/lint.cjs +27 -13
- package/dist/lint.js +2 -1
- package/dist/react.cjs +2 -1
- package/dist/upgrade-steps.d.ts +1 -1
- package/dist/upgrade.cjs +2 -1
- package/package.json +1 -1
- package/skills/df-ps-implement/SKILL.md +2 -1
- package/skills/df-ps-scaffold/references/choosing-components.md +2 -1
- package/skills/df-ps-scaffold/references/units/port.md +2 -2
package/README.md
CHANGED
|
@@ -88,7 +88,8 @@ All settings and saved implementation types live in `domain-first.project-struct
|
|
|
88
88
|
"layers": true,
|
|
89
89
|
"dependencies": true,
|
|
90
90
|
"react": true,
|
|
91
|
-
"clock": true
|
|
91
|
+
"clock": true,
|
|
92
|
+
"config": true
|
|
92
93
|
}
|
|
93
94
|
}
|
|
94
95
|
},
|
|
@@ -283,13 +284,13 @@ The endpoint generator and the in-memory DB are what `df-init` scaffolds; as int
|
|
|
283
284
|
npx df-lint
|
|
284
285
|
```
|
|
285
286
|
|
|
286
|
-
It reports what breaks the Domain-First rules: forbidden imports between bounded contexts, imports against the layers, modules using kinds the dependency rules don't allow (in imports and in wiring), React modules importing what they shouldn't, and reading the time without the clock
|
|
287
|
+
It reports what breaks the Domain-First rules: forbidden imports between bounded contexts, imports against the layers, modules using kinds the dependency rules don't allow (in imports and in wiring), React modules importing what they shouldn't, and reading the time or environment variables without the clock and config ports. It exits with 1 when something is found, so you can run it in CI.
|
|
287
288
|
|
|
288
289
|
`df-init` scaffolds all standard rules into `backend.rules` during backend setup. Teams can edit these entries directly: what each kind of module may depend on (`backend.rules.dependencies`) and which checks run (`backend.rules.lint`). `df-scaffold` offers dependencies by the same rules. For older or manually shortened configs without `backend.rules`, the defaults apply and every check runs; kinds and checks you don't mention keep their defaults.
|
|
289
290
|
|
|
290
291
|
- Kinds in `backend.rules.dependencies` (as keys and in lists): `repositories`, `domain-services`, `application-ports`, `application-services`, `use-cases`, `commands`, `queries`, `infrastructure-services`, `presentation-services`.
|
|
291
292
|
- A kind's value: a list that replaces its defaults, or `{ "add": [...], "remove": [...] }`.
|
|
292
|
-
- Checks in `backend.rules.lint`: `context-isolation`, `shared-kernel`, `layers`, `dependencies`, `react`, `clock`.
|
|
293
|
+
- Checks in `backend.rules.lint`: `context-isolation`, `shared-kernel`, `layers`, `dependencies`, `react`, `clock`, `config`.
|
|
293
294
|
|
|
294
295
|
Defaults and details: [Dependency rules](API.md#dependency-rules), [`df-lint`](API.md#df-lint).
|
|
295
296
|
|
package/dist/38.js
CHANGED
|
@@ -225,7 +225,19 @@ const wiringViolations = (projectRoot, rootFolder, rules)=>{
|
|
|
225
225
|
}
|
|
226
226
|
return violations;
|
|
227
227
|
};
|
|
228
|
-
const
|
|
228
|
+
const directReadChecks = [
|
|
229
|
+
{
|
|
230
|
+
check: 'clock',
|
|
231
|
+
pattern: /\bnew\s+Date\s*\(\s*\)|\bDate\.now\s*\(/g,
|
|
232
|
+
rule: 'domain or application reads the current time directly (use the clock port):'
|
|
233
|
+
},
|
|
234
|
+
{
|
|
235
|
+
check: 'config',
|
|
236
|
+
pattern: /\bprocess\s*\??\.\s*env\b|\bprocess\s*\[\s*(['"`])env\1\s*\]|\bimport\.meta\.env\b/g,
|
|
237
|
+
rule: 'domain or application reads environment variables directly (use the config port):'
|
|
238
|
+
}
|
|
239
|
+
];
|
|
240
|
+
const directReadViolations = (projectRoot, rootFolder)=>{
|
|
229
241
|
const root = node_path.resolve(projectRoot, rootFolder);
|
|
230
242
|
const folders = [
|
|
231
243
|
node_path.join(root, 'shared-kernel'),
|
|
@@ -236,21 +248,21 @@ const clockViolations = (projectRoot, rootFolder)=>{
|
|
|
236
248
|
]);
|
|
237
249
|
return folders.flatMap(sourceFiles).filter((file)=>!isSpec(file)).flatMap((file)=>{
|
|
238
250
|
const source = node_fs.readFileSync(file, 'utf8');
|
|
239
|
-
return [
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
251
|
+
return directReadChecks.flatMap(({ check, pattern, rule })=>[
|
|
252
|
+
...source.matchAll(pattern)
|
|
253
|
+
].map((match)=>({
|
|
254
|
+
check,
|
|
255
|
+
rule,
|
|
256
|
+
file,
|
|
257
|
+
line: lineAt(source, match.index),
|
|
258
|
+
text: match[0]
|
|
259
|
+
})));
|
|
248
260
|
});
|
|
249
261
|
};
|
|
250
262
|
const lintProject = (projectRoot, rootFolder, { rules = defaultDependencyRules, checks = {} } = {})=>[
|
|
251
263
|
...importViolations(projectRoot, rootFolder, rules),
|
|
252
264
|
...wiringViolations(projectRoot, rootFolder, rules),
|
|
253
|
-
...
|
|
265
|
+
...directReadViolations(projectRoot, rootFolder)
|
|
254
266
|
].filter((x)=>false !== checks[x.check]);
|
|
255
267
|
const formatViolations = (violations, projectRoot)=>{
|
|
256
268
|
const groups = new Map();
|
package/dist/870.js
CHANGED
package/dist/agent-cli.d.ts
CHANGED
|
@@ -331,7 +331,7 @@ export declare const describeAgentCommand: (command: AgentCommand) => {
|
|
|
331
331
|
add?: ("queries" | "commands" | "use-cases" | "application-ports" | "repositories" | "domain-services" | "application-services" | "infrastructure-services" | "presentation-services")[] | undefined;
|
|
332
332
|
remove?: ("queries" | "commands" | "use-cases" | "application-ports" | "repositories" | "domain-services" | "application-services" | "infrastructure-services" | "presentation-services")[] | undefined;
|
|
333
333
|
}>> | undefined;
|
|
334
|
-
lint?: Partial<Record<"context-isolation" | "shared-kernel" | "layers" | "dependencies" | "react" | "clock", boolean>> | undefined;
|
|
334
|
+
lint?: Partial<Record<"context-isolation" | "shared-kernel" | "layers" | "dependencies" | "react" | "clock" | "config", boolean>> | undefined;
|
|
335
335
|
} | undefined;
|
|
336
336
|
} | undefined;
|
|
337
337
|
frontend?: {
|
package/dist/config-file.d.ts
CHANGED
|
@@ -2,7 +2,7 @@ import z from 'zod';
|
|
|
2
2
|
/**
|
|
3
3
|
* `df-lint` checks that `backend.rules.lint` can turn off.
|
|
4
4
|
*/
|
|
5
|
-
export declare const lintChecks: readonly ["context-isolation", "shared-kernel", "layers", "dependencies", "react", "clock"];
|
|
5
|
+
export declare const lintChecks: readonly ["context-isolation", "shared-kernel", "layers", "dependencies", "react", "clock", "config"];
|
|
6
6
|
export type LintCheck = (typeof lintChecks)[number];
|
|
7
7
|
export declare const configFileName = "domain-first.project-structure.config.json";
|
|
8
8
|
export declare const projectConfigSchema: z.ZodObject<{
|
|
@@ -61,6 +61,7 @@ export declare const rulesSchema: z.ZodObject<{
|
|
|
61
61
|
dependencies: "dependencies";
|
|
62
62
|
react: "react";
|
|
63
63
|
clock: "clock";
|
|
64
|
+
config: "config";
|
|
64
65
|
}> & z.core.$partial, z.ZodBoolean>>;
|
|
65
66
|
}, z.core.$strip>;
|
|
66
67
|
export declare const branchNameSchema: z.ZodString;
|
|
@@ -148,6 +149,7 @@ export declare const backendConfigSchema: z.ZodObject<{
|
|
|
148
149
|
dependencies: "dependencies";
|
|
149
150
|
react: "react";
|
|
150
151
|
clock: "clock";
|
|
152
|
+
config: "config";
|
|
151
153
|
}> & z.core.$partial, z.ZodBoolean>>;
|
|
152
154
|
}, z.core.$strip>>;
|
|
153
155
|
}, z.core.$loose>;
|
|
@@ -246,6 +248,7 @@ export declare const configSchema: z.ZodObject<{
|
|
|
246
248
|
dependencies: "dependencies";
|
|
247
249
|
react: "react";
|
|
248
250
|
clock: "clock";
|
|
251
|
+
config: "config";
|
|
249
252
|
}> & z.core.$partial, z.ZodBoolean>>;
|
|
250
253
|
}, z.core.$strip>>;
|
|
251
254
|
}, z.core.$loose>>;
|
package/dist/graph.cjs
CHANGED
package/dist/index.cjs
CHANGED
|
@@ -370,7 +370,8 @@ const lintChecks = [
|
|
|
370
370
|
'layers',
|
|
371
371
|
'dependencies',
|
|
372
372
|
'react',
|
|
373
|
-
'clock'
|
|
373
|
+
'clock',
|
|
374
|
+
'config'
|
|
374
375
|
];
|
|
375
376
|
const config_file_configFileName = 'domain-first.project-structure.config.json';
|
|
376
377
|
const projectConfigSchema = external_zod_default().object({
|
package/dist/init.cjs
CHANGED
|
@@ -298,7 +298,8 @@ const lintChecks = [
|
|
|
298
298
|
'layers',
|
|
299
299
|
'dependencies',
|
|
300
300
|
'react',
|
|
301
|
-
'clock'
|
|
301
|
+
'clock',
|
|
302
|
+
'config'
|
|
302
303
|
];
|
|
303
304
|
const config_file_configFileName = 'domain-first.project-structure.config.json';
|
|
304
305
|
const projectConfigSchema = external_zod_default().object({
|
package/dist/integration.cjs
CHANGED
|
@@ -369,7 +369,8 @@ const lintChecks = [
|
|
|
369
369
|
'layers',
|
|
370
370
|
'dependencies',
|
|
371
371
|
'react',
|
|
372
|
-
'clock'
|
|
372
|
+
'clock',
|
|
373
|
+
'config'
|
|
373
374
|
];
|
|
374
375
|
const config_file_configFileName = 'domain-first.project-structure.config.json';
|
|
375
376
|
const projectConfigSchema = external_zod_default().object({
|
package/dist/lint.cjs
CHANGED
|
@@ -238,7 +238,8 @@ const lintChecks = [
|
|
|
238
238
|
'layers',
|
|
239
239
|
'dependencies',
|
|
240
240
|
'react',
|
|
241
|
-
'clock'
|
|
241
|
+
'clock',
|
|
242
|
+
'config'
|
|
242
243
|
];
|
|
243
244
|
const configFileName = 'domain-first.project-structure.config.json';
|
|
244
245
|
const projectConfigSchema = external_zod_default().object({
|
|
@@ -891,7 +892,19 @@ const wiringViolations = (projectRoot, rootFolder, rules)=>{
|
|
|
891
892
|
}
|
|
892
893
|
return violations;
|
|
893
894
|
};
|
|
894
|
-
const
|
|
895
|
+
const directReadChecks = [
|
|
896
|
+
{
|
|
897
|
+
check: 'clock',
|
|
898
|
+
pattern: /\bnew\s+Date\s*\(\s*\)|\bDate\.now\s*\(/g,
|
|
899
|
+
rule: 'domain or application reads the current time directly (use the clock port):'
|
|
900
|
+
},
|
|
901
|
+
{
|
|
902
|
+
check: 'config',
|
|
903
|
+
pattern: /\bprocess\s*\??\.\s*env\b|\bprocess\s*\[\s*(['"`])env\1\s*\]|\bimport\.meta\.env\b/g,
|
|
904
|
+
rule: 'domain or application reads environment variables directly (use the config port):'
|
|
905
|
+
}
|
|
906
|
+
];
|
|
907
|
+
const directReadViolations = (projectRoot, rootFolder)=>{
|
|
895
908
|
const root = external_node_path_default().resolve(projectRoot, rootFolder);
|
|
896
909
|
const folders = [
|
|
897
910
|
external_node_path_default().join(root, 'shared-kernel'),
|
|
@@ -902,21 +915,21 @@ const clockViolations = (projectRoot, rootFolder)=>{
|
|
|
902
915
|
]);
|
|
903
916
|
return folders.flatMap(sourceFiles).filter((file)=>!isSpec(file)).flatMap((file)=>{
|
|
904
917
|
const source = external_node_fs_default().readFileSync(file, 'utf8');
|
|
905
|
-
return [
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
918
|
+
return directReadChecks.flatMap(({ check, pattern, rule })=>[
|
|
919
|
+
...source.matchAll(pattern)
|
|
920
|
+
].map((match)=>({
|
|
921
|
+
check,
|
|
922
|
+
rule,
|
|
923
|
+
file,
|
|
924
|
+
line: lineAt(source, match.index),
|
|
925
|
+
text: match[0]
|
|
926
|
+
})));
|
|
914
927
|
});
|
|
915
928
|
};
|
|
916
929
|
const lintProject = (projectRoot, rootFolder, { rules = defaultDependencyRules, checks = {} } = {})=>[
|
|
917
930
|
...importViolations(projectRoot, rootFolder, rules),
|
|
918
931
|
...wiringViolations(projectRoot, rootFolder, rules),
|
|
919
|
-
...
|
|
932
|
+
...directReadViolations(projectRoot, rootFolder)
|
|
920
933
|
].filter((x)=>false !== checks[x.check]);
|
|
921
934
|
const formatViolations = (violations, projectRoot)=>{
|
|
922
935
|
const groups = new Map();
|
|
@@ -935,7 +948,8 @@ const help = `Usage: df-lint [rootFolder]
|
|
|
935
948
|
|
|
936
949
|
Reports what breaks the Domain-First rules in the project:
|
|
937
950
|
bounded context isolation, layers, dependency rules (imports and wiring),
|
|
938
|
-
React modules, and reading the time
|
|
951
|
+
React modules, and reading the time or environment variables without
|
|
952
|
+
the clock and config ports.
|
|
939
953
|
rootFolder defaults to the one in domain-first.project-structure.config.json,
|
|
940
954
|
whose optional \`backend.rules\` change the dependency rules and turn checks off.
|
|
941
955
|
Exits with 1 when something is found.
|
package/dist/lint.js
CHANGED
|
@@ -6,7 +6,8 @@ const help = `Usage: df-lint [rootFolder]
|
|
|
6
6
|
|
|
7
7
|
Reports what breaks the Domain-First rules in the project:
|
|
8
8
|
bounded context isolation, layers, dependency rules (imports and wiring),
|
|
9
|
-
React modules, and reading the time
|
|
9
|
+
React modules, and reading the time or environment variables without
|
|
10
|
+
the clock and config ports.
|
|
10
11
|
rootFolder defaults to the one in domain-first.project-structure.config.json,
|
|
11
12
|
whose optional \`backend.rules\` change the dependency rules and turn checks off.
|
|
12
13
|
Exits with 1 when something is found.
|
package/dist/react.cjs
CHANGED
|
@@ -370,7 +370,8 @@ const lintChecks = [
|
|
|
370
370
|
'layers',
|
|
371
371
|
'dependencies',
|
|
372
372
|
'react',
|
|
373
|
-
'clock'
|
|
373
|
+
'clock',
|
|
374
|
+
'config'
|
|
374
375
|
];
|
|
375
376
|
const config_file_configFileName = 'domain-first.project-structure.config.json';
|
|
376
377
|
const projectConfigSchema = external_zod_default().object({
|
package/dist/upgrade-steps.d.ts
CHANGED
|
@@ -65,7 +65,7 @@ export declare const planUpgrade: (config: unknown, acceptOptional?: (step: Plan
|
|
|
65
65
|
add?: ("queries" | "commands" | "use-cases" | "application-ports" | "repositories" | "domain-services" | "application-services" | "infrastructure-services" | "presentation-services")[] | undefined;
|
|
66
66
|
remove?: ("queries" | "commands" | "use-cases" | "application-ports" | "repositories" | "domain-services" | "application-services" | "infrastructure-services" | "presentation-services")[] | undefined;
|
|
67
67
|
}>> | undefined;
|
|
68
|
-
lint?: Partial<Record<"context-isolation" | "shared-kernel" | "layers" | "dependencies" | "react" | "clock", boolean>> | undefined;
|
|
68
|
+
lint?: Partial<Record<"context-isolation" | "shared-kernel" | "layers" | "dependencies" | "react" | "clock" | "config", boolean>> | undefined;
|
|
69
69
|
} | undefined;
|
|
70
70
|
} | undefined;
|
|
71
71
|
frontend?: {
|
package/dist/upgrade.cjs
CHANGED
package/package.json
CHANGED
|
@@ -42,7 +42,8 @@ Run it from the project root; `rootFolder` defaults to the config's. It resolves
|
|
|
42
42
|
- imports against the layers ("Ground rules"; specs excluded);
|
|
43
43
|
- module files importing kinds the project's dependency rules don't allow (a use case importing a use case, a query importing a command, …), and wired dependencies they don't allow ("Wiring" below, `df-ps-scaffold` rule 3); an implementation importing its own contract is fine;
|
|
44
44
|
- a widget importing another widget (a widget = the nearest folder under `presentation/react/widgets/` with a `*-widget.tsx`, nested widgets included), UI-kit importing widgets, pages or contexts, shared hooks importing UI-kit, widgets, pages or contexts;
|
|
45
|
-
- `new Date()` / `Date.now()` in domain or application (use the `clock` port)
|
|
45
|
+
- `new Date()` / `Date.now()` in domain or application (use the `clock` port);
|
|
46
|
+
- `process.env` / `import.meta.env` in domain or application (use the `config` port).
|
|
46
47
|
|
|
47
48
|
It exits with 1 when anything is found. Checks turned off in the config (`backend.rules.lint`) aren't reported; don't turn checks off yourself.
|
|
48
49
|
|
|
@@ -57,11 +57,12 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
|
|
|
57
57
|
| Application / infrastructure service | Used by use cases → application. Only by adapters/repositories → infrastructure. |
|
|
58
58
|
| Logic infrastructure needs from an application service | Infrastructure never sees application services. Pure logic without ports → domain service. Logic over ports → infrastructure calls the ports directly. Technical (mapping, retries, external API formats) → infrastructure service. |
|
|
59
59
|
| Clock | Always a port (`clock`, usually in Shared Kernel). A command or query never uses it: the use case reads the time and passes it in the input. |
|
|
60
|
+
| Configuration | Values application logic needs (limits, feature flags) → a port (`config`, usually in Shared Kernel), with methods in the application's terms. Settings only an adapter needs (connection strings, API keys) → that adapter or its infrastructure service reads them; no port. |
|
|
60
61
|
|
|
61
62
|
## Where it goes
|
|
62
63
|
|
|
63
64
|
- Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
|
|
64
|
-
- Shared Kernel: technical, ownerless pieces (`clock`, `mailer` ports, shared HTTP client, errors like `unauthorized`) and **universal** entities / value objects: the same meaning and rules in every context, owned by none (`money`, `email`, `address`). A Shared Kernel domain service holds rules at the junction of these universal types only. Anything with one context's meaning or rules (`order-status`, `customer`) stays in that context, even if other contexts need it; they duplicate it in the models of their own ports.
|
|
65
|
+
- Shared Kernel: technical, ownerless pieces (`clock`, `config`, `mailer` ports, shared HTTP client, errors like `unauthorized`) and **universal** entities / value objects: the same meaning and rules in every context, owned by none (`money`, `email`, `address`). A Shared Kernel domain service holds rules at the junction of these universal types only. Anything with one context's meaning or rules (`order-status`, `customer`) stays in that context, even if other contexts need it; they duplicate it in the models of their own ports.
|
|
65
66
|
- Another context's data or behavior → an application port in the consuming context (step 9).
|
|
66
67
|
|
|
67
68
|
## Example
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Port
|
|
2
2
|
|
|
3
|
-
When: a capability across this context's boundary: another bounded context, an external system, or
|
|
3
|
+
When: a capability across this context's boundary: another bounded context, an external system, time or configuration (`../choosing-components.md`, steps 9–10). Own aggregate persistence → repository; atomic operations on this context's own storage → command/query. One method is enough. Wanting to mock a class or imagining multiple implementations does not by itself establish a boundary. The `clock` and `config` ports usually belong in the Shared Kernel.
|
|
4
4
|
|
|
5
5
|
## Generate (context and Shared Kernel)
|
|
6
6
|
|
|
@@ -19,7 +19,7 @@ Prompts: name → primary adapter select → `With test implementation` → test
|
|
|
19
19
|
- For another context, define the port in the consuming context with its own models and errors. A `cross-context` adapter can inject queries, commands and use cases from any neighboring context; choices are labelled `(<context>)` and names get context-qualified aliases. Only this adapter imports neighboring handler types, and only its matching wiring imports their factories. Never import foreign models, errors, repositories, ports, services, infrastructure or barrels.
|
|
20
20
|
- Implement the capability's methods by mapping input, invoking injected handlers, and mapping results/errors. The CLI creates the contract, adapters and dependencies; it does not generate methods or delegation. Keep business coordination in the consuming use case.
|
|
21
21
|
- One implementation per adapter: `api` performs the real interaction (an SDK or HTTP client, through an [infrastructure service](services.md) for the client); `mock`/`fake` is deterministic.
|
|
22
|
-
- Use the Shared Kernel `clock` port instead of `new Date()` / `Date.now()` in domain and application code.
|
|
22
|
+
- Use the Shared Kernel `clock` port instead of `new Date()` / `Date.now()` in domain and application code, and a `config` port instead of `process.env` / `import.meta.env`. Its adapter reads the environment; infrastructure and wiring may read it directly.
|
|
23
23
|
|
|
24
24
|
## Test
|
|
25
25
|
|