@brutalway/check-tree 0.10.1 → 0.12.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
@@ -1,6 +1,6 @@
1
1
  # @brutalway/check-tree
2
2
 
3
- Checks the folders of a source tree, which a linter does not see: only the folders the layout names, no empty folder, no category folder with a single child, files of one kind grouped in that kind's folder once there are two of them, no file in a slice of `shared/` that a single feature uses, and no slice whose files never import each other.
3
+ Checks the folders of a source tree, which a linter does not see: only the folders the layout names, no empty folder, no kind folder with a single child, files of one kind grouped in that kind's folder once there are two of them, no file in a shared feature that a single feature uses, and no shared feature whose files never import each other.
4
4
 
5
5
  ## Install
6
6
 
@@ -29,7 +29,7 @@ check-tree reads its options from the `"check-tree"` key of the `package.json` i
29
29
 
30
30
  Each key has a flag, `--categories`, `--root-entries` and `--platforms`, which wins over the key for one run.
31
31
 
32
- ### Use your own category folders
32
+ ### Use your own kind folders
33
33
 
34
34
  `categories` lists the kind folders the layout accepts, and the grouping rule only applies to the kinds listed in the table below that are also in this list.
35
35
 
@@ -65,7 +65,7 @@ import { treeViolations } from '@brutalway/check-tree/treeViolations';
65
65
  const violations = treeViolations('src');
66
66
  ```
67
67
 
68
- It takes the category folders as second argument and `{ rootEntries: true, platforms: ['web'] }` as third, like `--categories`, `--root-entries` and `--platforms`. The checks on the slices of `shared/` read the imports, so they have their own export, which takes the platforms as second argument:
68
+ It takes the kind folders as second argument and `{ rootEntries: true, platforms: ['web'] }` as third, like `--categories`, `--root-entries` and `--platforms`. The checks on the shared features read the imports, so they have their own export, which takes the platforms as second argument:
69
69
 
70
70
  ```ts
71
71
  import { sharedViolations } from '@brutalway/check-tree/sharedViolations';
@@ -78,12 +78,12 @@ const violations = await sharedViolations('src');
78
78
  ### Rules
79
79
 
80
80
  - a folder has a name the layout gives it:
81
- - `src/` holds `app/`, `features/` and `shared/`, next to its entry files. `app/` belongs to the router, so its folders are not checked and its files stay where they are, whatever their kind
82
- - a `shared/`, at any depth, holds one folder per slice, named after its concept (`shared/todos/`, `shared/errors/`), and no file
83
- - a feature (`features/<x>/`) or a slice (`shared/<x>/`), at any depth, holds kind folders, `features/` for its sub-features and `shared/` for the slices they share
81
+ - `src/` holds `app/`, `features/` and `shared/`, next to its entry points. `app/` belongs to the router, so its folders are not checked and its files stay where they are, whatever their kind
82
+ - a `shared/`, at any depth, holds one folder per shared feature, named after its concept (`shared/todos/`, `shared/errors/`), and no file
83
+ - a feature (`features/<x>/`) or a shared feature (`shared/<x>/`), at any depth, holds kind folders, `features/` for its sub-features and `shared/` for the shared features they have in common
84
84
  - a kind folder holds kind folders only, like `presenters/` inside `components/`
85
85
  - no empty folder
86
- - a category folder (`components`, `hooks`, `stores`…) does not hold a single child: move the child up and delete the folder
86
+ - a kind folder (`components`, `hooks`, `stores`…) does not hold a single child: move the child up and delete the folder
87
87
  - files of one kind stay at the root of their folder while there is one of them, and move into the kind's folder from two on. A folder that has that kind's folder keeps none of them next to it. The kinds are recognized by their name:
88
88
 
89
89
  | Folder | Files |
@@ -105,8 +105,8 @@ const violations = await sharedViolations('src');
105
105
  | `stores/` | `xStore.ts` |
106
106
  | `lib/` | any other `.ts` file, except `xContent.ts`, `xEnv.ts` and `.d.ts` |
107
107
 
108
- - a file of a slice is used by at least two consumers. For `src/shared/`, a consumer is a feature or another slice, a sub-feature counting as the feature it sits in. For the `shared/` of a feature or a slice, a consumer is one of its sub-features, another of its slices, or its own files outside them. A file imported by another file of the same slice gets the consumers of that file. A test counts for the feature it sits in, since moving the file would make that test import another feature, and a test next to the file in the slice adds no consumer. A file of `src/shared/` used only by `app/` or by the entry files of `src/` passes. A file with a single consumer gets `src/shared/dates/format.ts is only used by src/features/cart: move it into src/features/cart`, which also catches a whole slice used by one feature.
109
- - the files of a slice, tests aside, form one group in the import graph, whatever the direction of the imports. Since two slices never import each other, the folder then only names a boundary the graph already draws. A `shared/utils/` holding `errorMessage.ts`, `isRecord.ts` and `packageRoot.ts`, which do not import each other, gets `src/shared/utils holds 3 groups of files that never import each other (errorMessage.ts) (isRecord.ts) (packageRoot.ts): split it into one slice per group`. A slice of a single file is fine.
108
+ - a file of a shared feature is used by at least two consumers. For `src/shared/`, a consumer is a feature or another shared feature, a sub-feature counting as the feature it sits in. For the `shared/` of a feature or a shared feature, a consumer is one of its sub-features, another of its shared features, or its own files outside them. A file imported by another file of the same shared feature gets the consumers of that file. A test is never a consumer, wherever it sits: it exists for the code it covers and gives no reason to share it. A file that only tests import has no consumer at all and passes here, `knip --production` reports it. A file of `src/shared/` used only by `app/` or by the entry points of `src/` passes. A file with a single consumer gets `src/shared/dates/format.ts is only used by src/features/cart: move it into src/features/cart`, which also catches a whole shared feature used by one feature.
109
+ - the files of a shared feature, tests aside, form one group in the import graph, whatever the direction of the imports. Since two shared features never import each other, the folder then only names a boundary the graph already draws. A `shared/utils/` holding `errorMessage.ts`, `isRecord.ts` and `packageRoot.ts`, which do not import each other, gets `src/shared/utils holds 3 groups of files that never import each other (errorMessage.ts) (isRecord.ts) (packageRoot.ts): split it into one shared feature per group`. A shared feature of a single file is fine.
110
110
 
111
111
  The first of these two rules says why a file is shared, the second why files sit together. Each one lets through what the other catches: in the `shared/utils/` above, each file has two consumers.
112
112
 
@@ -114,7 +114,7 @@ So a feature with two components puts them in `components/`, and a `components/`
114
114
 
115
115
  Test files (`*.test.ts`, `*.test.tsx`) are not counted.
116
116
 
117
- The files of a folder named `X.<platform>.<ext>`, like `useScreenTitle.web.ts` and `useScreenTitle.native.ts`, go with `X.<ext>`, whether that file exists or not. The bundler picks them by name and nothing imports them, so the variants and their base count as one file: they have the kind of `X.<ext>` (`AvatarPhoto.web.tsx` is a presenter), a `lib/` holding only `alert.ts` and `alert.web.ts` holds a single child, and they belong to one group in the import graph of a slice. check-tree does not compare their exports: TypeScript checks the base only, unless `moduleSuffixes` in the tsconfig points it at a variant.
117
+ The files of a folder named `X.<platform>.<ext>`, like `useScreenTitle.web.ts` and `useScreenTitle.native.ts`, go with `X.<ext>`, whether that file exists or not. The bundler picks them by name and nothing imports them, so the variants and their base count as one file: they have the kind of `X.<ext>` (`AvatarPhoto.web.tsx` is a presenter), a `lib/` holding only `alert.ts` and `alert.web.ts` holds a single child, and they belong to one group in the import graph of a shared feature. check-tree does not compare their exports: TypeScript checks the base only, unless `moduleSuffixes` in the tsconfig points it at a variant.
118
118
 
119
119
  ### Output
120
120
 
package/dist/checkTree.js CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
- import { t as treeViolations } from "./treeViolations-DV1n3hcr.js";
3
- import { n as cruiseImports, t as sliceViolations } from "./sliceViolations-B4iDNwD2.js";
2
+ import { t as treeViolations } from "./treeViolations-BjinY4OB.js";
3
+ import { n as cruiseImports, t as sharedFeatureViolations } from "./sharedFeatureViolations-BbyKWb38.js";
4
4
  import { resolve } from "node:path";
5
5
  import { parseArgs } from "node:util";
6
6
  import { existsSync, readFileSync, writeFileSync } from "node:fs";
@@ -64,7 +64,7 @@ try {
64
64
  const violations = [...treeViolations(resolve(folder), categories, {
65
65
  rootEntries: values["root-entries"] === true || settings.rootEntries === true,
66
66
  platforms
67
- }), ...sliceViolations(folder, await cruiseImports(folder), platforms)];
67
+ }), ...sharedFeatureViolations(folder, await cruiseImports(folder), platforms)];
68
68
  if (values["write-known-violations"] === true) writeKnownViolations(violations, KNOWN_VIOLATIONS_FILE);
69
69
  else {
70
70
  const reported = unknownViolations(violations, KNOWN_VIOLATIONS_FILE);
@@ -29,8 +29,8 @@ async function cruiseImports(root) {
29
29
  }
30
30
  // src/features/shared-consumers/SharedConsumersConfig.ts
31
31
  const TEST_CODE = /\.test\.tsx?$/u;
32
- const SLICE = /^(?:features|shared)\/[^/]+/u;
33
- const SLICE_FILE = /^((.*)\/shared\/[^/]+)\//u;
32
+ const SUB_FEATURE_OR_SHARED_FEATURE = /^(?:features|shared)\/[^/]+/u;
33
+ const SHARED_FEATURE_FILE = /^((.*)\/shared\/[^/]+)\//u;
34
34
  // src/features/shared-consumers/lib/checkedPaths.ts
35
35
  function checkedPaths(checkedFolder) {
36
36
  const root = normalize(checkedFolder).replace(/\/$/u, "");
@@ -43,37 +43,40 @@ function checkedPaths(checkedFolder) {
43
43
  // src/features/shared-consumers/lib/consumerSlots.ts
44
44
  function slotOf(owner, importer) {
45
45
  if (!importer.startsWith(`${owner}/`)) return importer;
46
- const slice = SLICE.exec(importer.slice(owner.length + 1));
47
- return slice === null ? owner : `${owner}/${slice[0]}`;
46
+ const child = SUB_FEATURE_OR_SHARED_FEATURE.exec(importer.slice(owner.length + 1));
47
+ return child === null ? owner : `${owner}/${child[0]}`;
48
48
  }
49
49
  function unitOf(path, platforms) {
50
50
  return `${dirname(path)}/${platformBase(basename(path), platforms)}`;
51
51
  }
52
52
  function importersByUnit(modules, platforms) {
53
53
  const importers = /* @__PURE__ */ new Map();
54
- for (const { source, imports } of modules) for (const target of imports) {
55
- const unit = unitOf(target, platforms);
56
- importers.set(unit, [...importers.get(unit) ?? [], source]);
54
+ for (const { source, imports } of modules) {
55
+ if (TEST_CODE.test(source)) continue;
56
+ for (const target of imports) {
57
+ const unit = unitOf(target, platforms);
58
+ importers.set(unit, [...importers.get(unit) ?? [], source]);
59
+ }
57
60
  }
58
61
  return importers;
59
62
  }
60
63
  function consumerSlots(modules, platforms) {
61
64
  const importers = importersByUnit(modules, platforms);
62
65
  const slotsByModule = /* @__PURE__ */ new Map();
63
- return function slots(path, slice) {
64
- const key = `${slice.folder}:${path}`;
66
+ return function slots(path, sharedFeature) {
67
+ const key = `${sharedFeature.folder}:${path}`;
65
68
  const known = slotsByModule.get(key);
66
69
  if (known !== void 0) return known;
67
70
  const found = /* @__PURE__ */ new Set();
68
71
  slotsByModule.set(key, found);
69
- for (const importer of importers.get(unitOf(path, platforms)) ?? []) if (importer.startsWith(`${slice.folder}/`)) for (const slot of slots(importer, slice)) found.add(slot);
70
- else found.add(slotOf(slice.owner, importer));
72
+ for (const importer of importers.get(unitOf(path, platforms)) ?? []) if (importer.startsWith(`${sharedFeature.folder}/`)) for (const slot of slots(importer, sharedFeature)) found.add(slot);
73
+ else found.add(slotOf(sharedFeature.owner, importer));
71
74
  return found;
72
75
  };
73
76
  }
74
- // src/features/shared-consumers/lib/sliceOf.ts
75
- function sliceOf(path) {
76
- const [, folder, owner] = SLICE_FILE.exec(path) ?? [];
77
+ // src/features/shared-consumers/lib/sharedFeatureOf.ts
78
+ function sharedFeatureOf(path) {
79
+ const [, folder, owner] = SHARED_FEATURE_FILE.exec(path) ?? [];
77
80
  if (folder === void 0 || owner === void 0) return void 0;
78
81
  return {
79
82
  owner,
@@ -89,12 +92,12 @@ function sharedConsumerViolations(checkedFolder, modules, platforms) {
89
92
  const { root, shown } = checkedPaths(checkedFolder);
90
93
  const slots = consumerSlots(modules, platforms);
91
94
  return modules.flatMap(({ source }) => {
92
- const slice = sliceOf(source);
93
- if (slice === void 0 || TEST_CODE.test(source) || !source.startsWith(`${root}/`)) return [];
94
- const [slot, ...others] = slots(source, slice);
95
+ const sharedFeature = sharedFeatureOf(source);
96
+ if (sharedFeature === void 0 || TEST_CODE.test(source) || !source.startsWith(`${root}/`)) return [];
97
+ const [slot, ...others] = slots(source, sharedFeature);
95
98
  if (slot === void 0 || others.length > 0) return [];
96
- if (slice.owner === root && !SLICE.test(slot.slice(root.length + 1))) return [];
97
- return [violation(shown(source), shown(slice.owner), shown(slot))];
99
+ if (sharedFeature.owner === root && !SUB_FEATURE_OR_SHARED_FEATURE.test(slot.slice(root.length + 1))) return [];
100
+ return [violation(shown(source), shown(sharedFeature.owner), shown(slot))];
98
101
  });
99
102
  }
100
103
  // src/features/shared-consumers/lib/variantLinks.ts
@@ -108,12 +111,12 @@ function variantLinks(files, platforms) {
108
111
  return [];
109
112
  });
110
113
  }
111
- // src/features/shared-consumers/lib/sliceGroupViolations.ts
112
- function sliceFolders(root, modules) {
114
+ // src/features/shared-consumers/lib/sharedFeatureGroupViolations.ts
115
+ function sharedFeatureFolders(root, modules) {
113
116
  const folders = /* @__PURE__ */ new Map();
114
117
  for (const { source } of modules) {
115
- const slice = sliceOf(source);
116
- if (slice !== void 0 && !TEST_CODE.test(source) && source.startsWith(`${root}/`)) folders.set(source, slice.folder);
118
+ const sharedFeature = sharedFeatureOf(source);
119
+ if (sharedFeature !== void 0 && !TEST_CODE.test(source) && source.startsWith(`${root}/`)) folders.set(source, sharedFeature.folder);
117
120
  }
118
121
  return folders;
119
122
  }
@@ -132,27 +135,27 @@ function linkedGroups(files, links) {
132
135
  for (const [from, to] of links) parents.set(head(from), head(to));
133
136
  return head;
134
137
  }
135
- function groupsBySlice(folders, head) {
136
- const slices = /* @__PURE__ */ new Map();
138
+ function groupsBySharedFeature(folders, head) {
139
+ const sharedFeatures = /* @__PURE__ */ new Map();
137
140
  for (const [file, folder] of [...folders].toSorted(([a], [b]) => a.localeCompare(b))) {
138
- const groups = slices.get(folder) ?? /* @__PURE__ */ new Map();
141
+ const groups = sharedFeatures.get(folder) ?? /* @__PURE__ */ new Map();
139
142
  groups.set(head(file), [...groups.get(head(file)) ?? [], file.slice(folder.length + 1)]);
140
- slices.set(folder, groups);
143
+ sharedFeatures.set(folder, groups);
141
144
  }
142
- return slices;
145
+ return sharedFeatures;
143
146
  }
144
- function sliceGroupViolations(checkedFolder, modules, platforms) {
147
+ function sharedFeatureGroupViolations(checkedFolder, modules, platforms) {
145
148
  const { root, shown } = checkedPaths(checkedFolder);
146
- const folders = sliceFolders(root, modules);
149
+ const folders = sharedFeatureFolders(root, modules);
147
150
  const links = [...importLinks(modules, folders), ...variantLinks(folders.keys(), platforms)];
148
- return [...groupsBySlice(folders, linkedGroups(folders.keys(), links))].flatMap(([folder, groups]) => {
151
+ return [...groupsBySharedFeature(folders, linkedGroups(folders.keys(), links))].flatMap(([folder, groups]) => {
149
152
  if (groups.size < 2) return [];
150
153
  const listed = [...groups.values()].map((files) => `(${files.join(", ")})`).join(" ");
151
- return [`${shown(folder)} holds ${groups.size} groups of files that never import each other ${listed}: split it into one slice per group`];
154
+ return [`${shown(folder)} holds ${groups.size} groups of files that never import each other ${listed}: split it into one shared feature per group`];
152
155
  });
153
156
  }
154
- // src/features/shared-consumers/lib/sliceViolations.ts
155
- function sliceViolations(checkedFolder, modules, platforms) {
156
- return [...sharedConsumerViolations(checkedFolder, modules, platforms), ...sliceGroupViolations(checkedFolder, modules, platforms)];
157
+ // src/features/shared-consumers/lib/sharedFeatureViolations.ts
158
+ function sharedFeatureViolations(checkedFolder, modules, platforms) {
159
+ return [...sharedConsumerViolations(checkedFolder, modules, platforms), ...sharedFeatureGroupViolations(checkedFolder, modules, platforms)];
157
160
  }
158
- export { cruiseImports as n, sliceViolations as t };
161
+ export { cruiseImports as n, sharedFeatureViolations as t };
@@ -1,6 +1,6 @@
1
- import { n as cruiseImports, t as sliceViolations } from "./sliceViolations-B4iDNwD2.js";
1
+ import { n as cruiseImports, t as sharedFeatureViolations } from "./sharedFeatureViolations-BbyKWb38.js";
2
2
  // src/sharedViolations.ts
3
3
  async function sharedViolations(root, platforms) {
4
- return sliceViolations(root, await cruiseImports(root), platforms);
4
+ return sharedFeatureViolations(root, await cruiseImports(root), platforms);
5
5
  }
6
6
  export { sharedViolations };
@@ -121,9 +121,9 @@ const FILE_GROUPS = [
121
121
  const SOURCE_LAYERS = /* @__PURE__ */ new Map([
122
122
  ["app", "router"],
123
123
  ["features", "features"],
124
- ["shared", "slices"]
124
+ ["shared", "sharedFeatures"]
125
125
  ]);
126
- const FEATURE_LAYERS = /* @__PURE__ */ new Map([["features", "features"], ["shared", "slices"]]);
126
+ const FEATURE_LAYERS = /* @__PURE__ */ new Map([["features", "features"], ["shared", "sharedFeatures"]]);
127
127
  function kindFolder(path, categories, reason) {
128
128
  if (categories.has(basename(path))) return {
129
129
  layer: "kind",
@@ -142,7 +142,7 @@ function sourceChild(path) {
142
142
  };
143
143
  return {
144
144
  layer: "free",
145
- violations: [`${path} is not a layer: ${dirname(path)}/ holds app/, features/ and shared/ next to its entry files, move it into one of them`]
145
+ violations: [`${path} is not a layer: ${dirname(path)}/ holds app/, features/ and shared/ next to its entry points, move it into one of them`]
146
146
  };
147
147
  }
148
148
  function featureChild(path, categories) {
@@ -151,11 +151,11 @@ function featureChild(path, categories) {
151
151
  layer,
152
152
  violations: []
153
153
  };
154
- return kindFolder(path, categories, "a feature or a slice holds kind folders, features/ for its sub-features and shared/ for the slices they share, move it into features/ as a sub-feature, into shared/ as a slice, or spread its files into kind folders");
154
+ return kindFolder(path, categories, "a feature or a shared feature holds kind folders, features/ for its sub-features and shared/ for the shared features they have in common, move it into features/ as a sub-feature, into shared/ as a shared feature, or spread its files into kind folders");
155
155
  }
156
156
  function childLayer(layer, path, categories) {
157
157
  if (layer === "source") return sourceChild(path);
158
- if (layer === "features" || layer === "slices") return {
158
+ if (layer === "features" || layer === "sharedFeatures") return {
159
159
  layer: "feature",
160
160
  violations: []
161
161
  };
@@ -172,13 +172,13 @@ function childLayer(layer, path, categories) {
172
172
  }
173
173
  // src/features/tree-violations/features/layout/lib/filesCheck.ts
174
174
  function filesCheck(layer, holdsEntries) {
175
- if (layer === "slices") return "slices";
175
+ if (layer === "sharedFeatures") return "sharedFeatures";
176
176
  return layer === "router" || holdsEntries ? "none" : "groups";
177
177
  }
178
- // src/features/tree-violations/features/layout/lib/sliceFileViolations.ts
179
- function sliceFileViolations(name, files) {
178
+ // src/features/tree-violations/features/layout/lib/sharedRootFileViolations.ts
179
+ function sharedRootFileViolations(name, files) {
180
180
  if (files.length === 0) return [];
181
- return [`${name} holds ${files.join(", ")}: shared/ holds one folder per slice, move each file into the slice of its concept`];
181
+ return [`${name} holds ${files.join(", ")}: shared/ holds one folder per shared feature, move each file into the shared feature of its concept`];
182
182
  }
183
183
  // src/features/tree-violations/treeViolations.ts
184
184
  function groupViolations(name, folderName, listing, categoryFolders) {
@@ -208,7 +208,7 @@ function folderViolations(folder, name, scan, check) {
208
208
  const children = readdirSync(folder, { withFileTypes: true }).filter((entry) => !TEST_FILE.test(entry.name));
209
209
  const listing = folderListing(children, scan.platforms);
210
210
  const violations = shapeViolations(name, new Set(listing.files.map(listing.baseOf)).size + children.length - listing.files.length, scan.categories.has(basename(folder)));
211
- if (check === "slices") return [...violations, ...sliceFileViolations(name, listing.files)];
211
+ if (check === "sharedFeatures") return [...violations, ...sharedRootFileViolations(name, listing.files)];
212
212
  if (check === "none") return violations;
213
213
  return [...violations, ...groupViolations(name, basename(folder), listing, scan.categories)];
214
214
  }
@@ -1 +1 @@
1
- export { t as treeViolations } from "./treeViolations-DV1n3hcr.js";
1
+ export { t as treeViolations } from "./treeViolations-BjinY4OB.js";
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@brutalway/check-tree",
3
- "version": "0.10.1",
4
- "description": "Checks a source tree: only the folders the layout names, no empty folder, no category folder holding a single child, stylesheets grouped in styles/, no file of a slice of shared/ used by a single feature, no slice whose files never import each other.",
3
+ "version": "0.12.0",
4
+ "description": "Checks a source tree: only the folders the layout names, no empty folder, no kind folder holding a single child, stylesheets grouped in styles/, no file of a shared feature used by a single feature, no shared feature whose files never import each other.",
5
5
  "keywords": [
6
6
  "lint",
7
7
  "folder-structure",