@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 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 port. It exits with 1 when something is found, so you can run it in CI.
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 clockViolations = (projectRoot, rootFolder)=>{
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
- ...source.matchAll(/\bnew\s+Date\s*\(\s*\)|\bDate\.now\s*\(/g)
241
- ].map((match)=>({
242
- check: 'clock',
243
- rule: 'domain or application reads the current time directly (use the clock port):',
244
- file,
245
- line: lineAt(source, match.index),
246
- text: match[0]
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
- ...clockViolations(projectRoot, rootFolder)
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
@@ -316,7 +316,8 @@ const lintChecks = [
316
316
  'layers',
317
317
  'dependencies',
318
318
  'react',
319
- 'clock'
319
+ 'clock',
320
+ 'config'
320
321
  ];
321
322
  const configFileName = 'domain-first.project-structure.config.json';
322
323
  const projectConfigSchema = zod.object({
@@ -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?: {
@@ -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
@@ -215,7 +215,8 @@ const lintChecks = [
215
215
  'layers',
216
216
  'dependencies',
217
217
  'react',
218
- 'clock'
218
+ 'clock',
219
+ 'config'
219
220
  ];
220
221
  const configFileName = 'domain-first.project-structure.config.json';
221
222
  const projectConfigSchema = external_zod_default().object({
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({
@@ -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 clockViolations = (projectRoot, rootFolder)=>{
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
- ...source.matchAll(/\bnew\s+Date\s*\(\s*\)|\bDate\.now\s*\(/g)
907
- ].map((match)=>({
908
- check: 'clock',
909
- rule: 'domain or application reads the current time directly (use the clock port):',
910
- file,
911
- line: lineAt(source, match.index),
912
- text: match[0]
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
- ...clockViolations(projectRoot, rootFolder)
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 without the clock port.
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 without the clock port.
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({
@@ -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
@@ -249,7 +249,8 @@ const lintChecks = [
249
249
  'layers',
250
250
  'dependencies',
251
251
  'react',
252
- 'clock'
252
+ 'clock',
253
+ 'config'
253
254
  ];
254
255
  const configFileName = 'domain-first.project-structure.config.json';
255
256
  const projectConfigSchema = external_zod_default().object({
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@domain-first/project-structure",
3
3
  "description": "Build and manage your Domain-First project structure with CLI",
4
- "version": "8.4.0",
4
+ "version": "8.5.0",
5
5
  "type": "module",
6
6
  "repository": {
7
7
  "type": "git",
@@ -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 time (`../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` port usually belongs in the Shared Kernel.
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