@brutalway/check-tree 0.0.0-stage → 0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 elnop
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,61 @@
1
- # Temporary Holding Version
1
+ # @brutalway/check-tree
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Checks the folders of a source tree, which a linter does not see:
4
+
5
+ - no empty folder
6
+ - a category folder (`components`, `hooks`, `stores`…) does not hold a single child: move the child up and delete the folder
7
+ - 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:
8
+
9
+ | Folder | Files |
10
+ | -------------------------------------- | ----------------------------------------------------------------- |
11
+ | `components/` | `X.tsx` in PascalCase, except `XContent.tsx` |
12
+ | `orchestrators/`, inside `components/` | components named `XContainer`, `XLayout` or `XPage` |
13
+ | `presenters/`, inside `components/` | the other components |
14
+ | `hooks/` | `useX.ts`, `useX.tsx` |
15
+ | `styles/` | `.css`, except `X.module.css`, which stays next to `X.tsx` |
16
+ | `types/` | `xTypes.ts` |
17
+ | `configs/` | `xConfig.ts` |
18
+ | `routes/` | `xRoutes.ts` |
19
+ | `services/` | `xService.ts` |
20
+ | `queries/` | `xQueries.ts` |
21
+ | `keys/` | `xKeys.ts`, query key factories |
22
+ | `schemas/` | `xSchemas.ts` |
23
+ | `clients/` | `xClient.ts` |
24
+ | `workers/` | `xWorker.ts` |
25
+ | `stores/` | `xStore.ts` |
26
+ | `lib/` | any other `.ts` file, except `xContent.ts`, `xEnv.ts` and `.d.ts` |
27
+
28
+ So a feature with two components puts them in `components/`, and a `components/` folder with two presenters puts them in `presenters/`. The `components/` rule does not apply inside `components/`, `orchestrators/` or `presenters/`.
29
+
30
+ Test files (`*.test.ts`, `*.test.tsx`) are not counted.
31
+
32
+ ```sh
33
+ npm install --save-dev @brutalway/check-tree
34
+ npx check-tree src
35
+ ```
36
+
37
+ It prints one line per problem and exits with code 1 if it found any.
38
+
39
+ The default category folders are `components`, `orchestrators`, `presenters`, `hooks`, `styles`, `types`, `configs`, `stores`, `routes`, `services`, `queries`, `keys`, `schemas`, `clients`, `workers` and `lib`. Pass your own list with `--categories`:
40
+
41
+ ```sh
42
+ npx check-tree src --categories components,hooks,utils
43
+ ```
44
+
45
+ The grouping rule only applies to the kinds listed in the table that are also in this list.
46
+
47
+ A published package keeps its entry points at the root of `src/`, one file per bin or export, whatever their kind. `--root-entries` leaves the files at the root of the checked folder where they are, and checks everything below as usual:
48
+
49
+ ```sh
50
+ npx check-tree src --root-entries
51
+ ```
52
+
53
+ The check is also exported as a function:
54
+
55
+ ```ts
56
+ import { treeViolations } from '@brutalway/check-tree/treeViolations';
57
+
58
+ const violations = treeViolations('src');
59
+ ```
60
+
61
+ It takes the category folders as second argument and `{ rootEntries: true }` as third, like `--categories` and `--root-entries`.
@@ -0,0 +1 @@
1
+ export {}
@@ -0,0 +1,17 @@
1
+ #!/usr/bin/env node
2
+ import { t as treeViolations } from "./treeViolations-DewMNsBO.js";
3
+ import { resolve } from "node:path";
4
+ import { parseArgs } from "node:util";
5
+ // src/checkTree.ts
6
+ const { values, positionals } = parseArgs({
7
+ allowPositionals: true,
8
+ options: {
9
+ categories: { type: "string" },
10
+ "root-entries": { type: "boolean" }
11
+ }
12
+ });
13
+ const categories = values.categories?.split(",").map((category) => category.trim());
14
+ const violations = treeViolations(resolve(positionals[0] ?? "src"), categories, { rootEntries: values["root-entries"] === true });
15
+ for (const violation of violations) console.error(violation);
16
+ process.exitCode = violations.length === 0 ? 0 : 1;
17
+ export {};
@@ -0,0 +1,146 @@
1
+ import { basename, join, relative } from "node:path";
2
+ import { readdirSync } from "node:fs";
3
+ // src/features/tree-violations/treeViolations.ts
4
+ const DEFAULT_CATEGORY_FOLDERS = [
5
+ "components",
6
+ "orchestrators",
7
+ "presenters",
8
+ "hooks",
9
+ "styles",
10
+ "types",
11
+ "configs",
12
+ "stores",
13
+ "routes",
14
+ "services",
15
+ "queries",
16
+ "keys",
17
+ "schemas",
18
+ "clients",
19
+ "workers",
20
+ "lib"
21
+ ];
22
+ const TEST_FILE = /\.test\.tsx?$/u;
23
+ const NAMED_FILE = /^use[A-Z]|(?:Types|Config|Store|Routes|Service|Queries|Keys|Schemas|Client|Worker|Env)\.ts$|Content\.tsx?$|\.d\.ts$/u;
24
+ const COMPONENT_FILE = /^[A-Z]\w*\.tsx$/u;
25
+ const ORCHESTRATOR_FILE = /(?:Container|Layout|Page)\.tsx$/u;
26
+ const COMPONENT_FOLDERS = /* @__PURE__ */ new Set([
27
+ "components",
28
+ "orchestrators",
29
+ "presenters"
30
+ ]);
31
+ function isComponent(fileName) {
32
+ return COMPONENT_FILE.test(fileName) && !NAMED_FILE.test(fileName);
33
+ }
34
+ function outsideOwnFolder(folder) {
35
+ return (folderName) => folderName !== folder;
36
+ }
37
+ const FILE_GROUPS = [
38
+ {
39
+ folder: "components",
40
+ belongs: isComponent,
41
+ appliesIn: (folderName) => !COMPONENT_FOLDERS.has(folderName)
42
+ },
43
+ {
44
+ folder: "orchestrators",
45
+ belongs: (fileName) => isComponent(fileName) && ORCHESTRATOR_FILE.test(fileName),
46
+ appliesIn: (folderName) => folderName === "components"
47
+ },
48
+ {
49
+ folder: "presenters",
50
+ belongs: (fileName) => isComponent(fileName) && !ORCHESTRATOR_FILE.test(fileName),
51
+ appliesIn: (folderName) => folderName === "components"
52
+ },
53
+ {
54
+ folder: "hooks",
55
+ belongs: (fileName) => /^use[A-Z]\w*\.tsx?$/u.test(fileName),
56
+ appliesIn: outsideOwnFolder("hooks")
57
+ },
58
+ {
59
+ folder: "styles",
60
+ belongs: (fileName) => fileName.endsWith(".css") && !fileName.endsWith(".module.css"),
61
+ appliesIn: outsideOwnFolder("styles")
62
+ },
63
+ {
64
+ folder: "types",
65
+ belongs: (fileName) => fileName.endsWith("Types.ts"),
66
+ appliesIn: outsideOwnFolder("types")
67
+ },
68
+ {
69
+ folder: "configs",
70
+ belongs: (fileName) => fileName.endsWith("Config.ts"),
71
+ appliesIn: outsideOwnFolder("configs")
72
+ },
73
+ {
74
+ folder: "stores",
75
+ belongs: (fileName) => fileName.endsWith("Store.ts"),
76
+ appliesIn: outsideOwnFolder("stores")
77
+ },
78
+ {
79
+ folder: "routes",
80
+ belongs: (fileName) => fileName.endsWith("Routes.ts"),
81
+ appliesIn: outsideOwnFolder("routes")
82
+ },
83
+ {
84
+ folder: "services",
85
+ belongs: (fileName) => fileName.endsWith("Service.ts"),
86
+ appliesIn: outsideOwnFolder("services")
87
+ },
88
+ {
89
+ folder: "queries",
90
+ belongs: (fileName) => fileName.endsWith("Queries.ts"),
91
+ appliesIn: outsideOwnFolder("queries")
92
+ },
93
+ {
94
+ folder: "keys",
95
+ belongs: (fileName) => fileName.endsWith("Keys.ts"),
96
+ appliesIn: outsideOwnFolder("keys")
97
+ },
98
+ {
99
+ folder: "schemas",
100
+ belongs: (fileName) => fileName.endsWith("Schemas.ts"),
101
+ appliesIn: outsideOwnFolder("schemas")
102
+ },
103
+ {
104
+ folder: "clients",
105
+ belongs: (fileName) => fileName.endsWith("Client.ts"),
106
+ appliesIn: outsideOwnFolder("clients")
107
+ },
108
+ {
109
+ folder: "workers",
110
+ belongs: (fileName) => fileName.endsWith("Worker.ts"),
111
+ appliesIn: outsideOwnFolder("workers")
112
+ },
113
+ {
114
+ folder: "lib",
115
+ belongs: (fileName) => fileName.endsWith(".ts") && !NAMED_FILE.test(fileName),
116
+ appliesIn: outsideOwnFolder("lib")
117
+ }
118
+ ];
119
+ function groupViolations(name, folderName, fileNames, folderNames, categoryFolders) {
120
+ const violations = [];
121
+ for (const { folder, belongs, appliesIn } of FILE_GROUPS) {
122
+ if (!categoryFolders.has(folder) || !appliesIn(folderName)) continue;
123
+ const loose = fileNames.filter(belongs);
124
+ if (loose.length === 0) continue;
125
+ if (folderNames.has(folder)) violations.push(`${name} has a ${folder}/ folder: move ${loose.join(", ")} into it`);
126
+ else if (loose.length > 1) violations.push(`${name} holds ${loose.length} ${folder} files (${loose.join(", ")}): move them into ${folder}/`);
127
+ }
128
+ return violations;
129
+ }
130
+ function folderViolations(folder, name, categoryFolders, groupsFiles) {
131
+ const children = readdirSync(folder, { withFileTypes: true }).filter((entry) => !TEST_FILE.test(entry.name));
132
+ const fileNames = children.filter((entry) => entry.isFile()).map((entry) => entry.name).toSorted();
133
+ const folderNames = new Set(children.filter((entry) => entry.isDirectory()).map((entry) => entry.name));
134
+ const violations = [];
135
+ if (children.length === 0) violations.push(`${name} is empty: delete it`);
136
+ if (children.length === 1 && categoryFolders.has(basename(folder))) violations.push(`${name} holds a single child: move it up one level and delete the folder`);
137
+ return groupsFiles ? [...violations, ...groupViolations(name, basename(folder), fileNames, folderNames, categoryFolders)] : violations;
138
+ }
139
+ function treeViolations(root, categoryFolders = DEFAULT_CATEGORY_FOLDERS, options = {}) {
140
+ const categories = new Set(categoryFolders);
141
+ function walk(folder) {
142
+ return [...folderViolations(folder, relative(join(root, ".."), folder), categories, folder !== root || options.rootEntries !== true), ...readdirSync(folder, { withFileTypes: true }).filter((entry) => entry.isDirectory()).flatMap((entry) => walk(join(folder, entry.name)))];
143
+ }
144
+ return walk(root);
145
+ }
146
+ export { treeViolations as t };
@@ -0,0 +1,5 @@
1
+ type TreeOptions = {
2
+ rootEntries?: boolean;
3
+ };
4
+ export declare function treeViolations(root: string, categoryFolders?: readonly string[], options?: TreeOptions): string[];
5
+ export {};
@@ -0,0 +1 @@
1
+ export { t as treeViolations } from "./treeViolations-DewMNsBO.js";
package/package.json CHANGED
@@ -1,6 +1,58 @@
1
1
  {
2
2
  "name": "@brutalway/check-tree",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.5.0",
4
+ "description": "Checks a source tree: no empty folder, no category folder holding a single child, stylesheets grouped in styles/.",
5
+ "keywords": [
6
+ "lint",
7
+ "folder-structure",
8
+ "project-structure",
9
+ "cli"
10
+ ],
11
+ "homepage": "https://github.com/Elnop/brutalway/tree/main/packages/tools/check-tree#readme",
12
+ "bugs": "https://github.com/Elnop/brutalway/issues",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/Elnop/brutalway.git",
16
+ "directory": "packages/tools/check-tree"
17
+ },
18
+ "license": "MIT",
19
+ "author": "elnop",
20
+ "type": "module",
21
+ "engines": {
22
+ "node": ">=26"
23
+ },
24
+ "files": [
25
+ "dist"
26
+ ],
27
+ "bin": {
28
+ "check-tree": "./dist/checkTree.js"
29
+ },
30
+ "exports": {
31
+ "./treeViolations": "./dist/treeViolations.js"
32
+ },
33
+ "scripts": {
34
+ "build": "tsdown",
35
+ "typecheck": "tsc -p .",
36
+ "lint": "oxlint --type-aware src oxlint.config.ts tsdown.config.ts",
37
+ "deps": "depcruise src",
38
+ "tree": "node src/checkTree.ts src --root-entries",
39
+ "duplicates": "jscpd src",
40
+ "check": "npm run typecheck && npm run lint && npm run deps && npm run tree && npm run duplicates",
41
+ "test": "node --test 'src/**/*.test.ts'"
42
+ },
43
+ "devDependencies": {
44
+ "@brutalway/dependency-cruiser-config": "0.5.0",
45
+ "@brutalway/oxlint-config-node": "0.2.0",
46
+ "@brutalway/oxlint-config-node-test": "0.1.0",
47
+ "@brutalway/tsconfig": "0.3.0",
48
+ "dependency-cruiser": "18.7.2",
49
+ "jscpd": "5.4.2",
50
+ "oxlint": "1.91.0",
51
+ "oxlint-tsgolint": "7.0.2005",
52
+ "tsdown": "0.23.5",
53
+ "typescript": "7.0.2"
54
+ },
55
+ "imports": {
56
+ "#src/*": "./src/*"
57
+ }
58
+ }