@adbayb/stack 0.0.0-next-912a585 → 0.0.0-next-ece28ab

package/README.md

@@ -59,19 +59,13 @@ stack release
 
 <br>
 
-## 🏗️ Architecture
+## 🌍 Ecosystem
 
-```mermaid
-flowchart TD
-    N("npm init @adbayb"):::strokeWidth -- Runs --> C("@adbayb/create"):::strokeWidth
-    C -- Runs --> S("@adbayb/stack"):::strokeWidth
-    S -- "Scaffolds (via template and shared configurations)" --> P("New project"):::strokeWidth
-    style C fill:#daf2d7,stroke:#90cf8e
-    style S fill:#daf2d7,stroke:#90cf8e
-    classDef strokeWidth stroke-width:3px
-```
+### Available configurations
 
-<br>
+- [@adbayb/stack/eslint](https://github.com/adbayb/stack/blob/main/stack/config/eslint/) to align logical and stylistic rules across projects.
+- [@adbayb/stack/prettier](https://github.com/adbayb/stack/blob/main/stack/config/prettier/) to align code formatting conventions across projects.
+- [@adbayb/stack/typescript](https://github.com/adbayb/stack/blob/main/stack/config/typescript/) to align type checking and processing across projects.
 
 ### Used technologies
 
@@ -87,15 +81,25 @@ flowchart TD
 - [Scripts](https://conventionalscripts.org/)
 - [File Structure](https://nx.dev/concepts/decisions/folder-structure)
   - Monorepo-first structure to:
-    - Keep a consistent file structure pattern across templates (ease template familiarity and onboarding)
-    - Ease examples setup
-    - Not clutter the published package with development-related context, metadata, and artifacts
+    - Keep a consistent file structure pattern across templates (ease template familiarity and onboarding).
+    - Ease examples setup.
+    - Not clutter the published package with development-related context, metadata, and artifacts.
 
 <br>
 
-## 👣 Roadmap
+## 🏗️ Architecture
+
+### Project creation workflow
 
-- [ ] `stack check`: Lint packages (caret range for dependencies and strict ones for dev dependencies)
+```mermaid
+flowchart TD
+    N("npm init @adbayb"):::strokeWidth -- Runs --> C("@adbayb/create"):::strokeWidth
+    C -- Runs --> S("@adbayb/stack create"):::strokeWidth
+    S -- "Scaffolds (via template and shared configurations)" --> P("New project"):::strokeWidth
+    style C fill:#daf2d7,stroke:#90cf8e
+    style S fill:#daf2d7,stroke:#90cf8e
+    classDef strokeWidth stroke-width:3px
+```
 
 <br>
 

package/config/eslint/README.md

@@ -8,7 +8,7 @@
 
 ## ✨ Features
 
-This package offers opinionated but extensible **[ESLint](https://eslint.org/)** configurations to align logical and stylistic rules across my projects.
+This package offers opinionated but extensible **[ESLint](https://eslint.org/)** configurations to align logical and stylistic rules across projects.
 
 It allows to:
 

package/config/prettier/README.md

@@ -8,7 +8,7 @@
 
 ## ✨ Features
 
-This package offers opinionated but extensible **[Prettier](https://prettier.io/)** configurations to align formatting rules and standards across my projects.
+This package offers opinionated but extensible **[Prettier](https://prettier.io/)** configurations to align code formatting conventions across projects.
 
 It allows to:
 

package/config/typescript/README.md

@@ -8,7 +8,7 @@
 
 ## ✨ Features
 
-This package offers opinionated but extensible **[TypeScript](https://www.typescriptlang.org/tsconfig/)** configurations to align type-checking and processing standards across my projects.
+This package offers opinionated but extensible **[TypeScript](https://www.typescriptlang.org/tsconfig/)** configurations to align type checking and processing across projects.
 
 It allows to:
 

package/dist/index.js

@@ -2,15 +2,20 @@ import { helpers, termost } from 'termost';
 import process from 'node:process';
 import { resolve, join } from 'node:path';
 import { createRequire } from 'node:module';
-import { existsSync, cpSync, readFileSync, renameSync, writeFileSync, readdirSync } from 'node:fs';
 import { writeFile, chmod, mkdir, symlink } from 'node:fs/promises';
+import { existsSync, cpSync, readFileSync, renameSync, writeFileSync, readdirSync } from 'node:fs';
 import { fdir } from 'fdir';
 
-var version = "0.0.0-next-912a585";
+var version = "0.0.0-next-ece28ab";
 
 const VERSION = version;
 
 const require = createRequire(import.meta.url);
+function assert(expectedCondition, createError) {
+    if (!expectedCondition) {
+        throw createError();
+    }
+}
 /**
  * Helper to format log messages with a welcoming bot.
  * @param input - Message factory.
@@ -58,6 +63,14 @@ ${input.body}
  */ const resolveFromStackDirectory = (path)=>{
     return resolve(import.meta.dirname, "../", path);
 };
+const createError = (bin, error)=>{
+    const errorMessage = `\`${bin}\` command failed.\n${String(error)}`;
+    if (error instanceof Error) {
+        error.message = errorMessage;
+        return error;
+    }
+    return new Error(errorMessage);
+};
 const getNpmVersion = async ()=>{
     try {
         return await helpers.exec("pnpm -v");
@@ -121,60 +134,6 @@ const eslint = (options)=>async (files = [])=>{
             throw createError("eslint", error);
         }
     };
-const checkLints = eslint({
-    isFixMode: false
-});
-const fixLints = eslint({
-    isFixMode: true
-});
-const fixFormatting = async (files)=>{
-    let prettierFiles = [];
-    if (files.length === 0) {
-        prettierFiles.push(`"**/!(${PRETTIER_IGNORE_FILES.join("|")})"`);
-    } else {
-        prettierFiles = files.filter((file)=>{
-            return !PRETTIER_IGNORE_FILES.some((filename)=>file.endsWith(filename)) && // The root `README.md` file is ignored to prevent error due to its symbolic link nature when specified explicitly as a file
-            file !== "README.md";
-        });
-        if (prettierFiles.length === 0) return Promise.resolve();
-    }
-    const args = [
-        ...prettierFiles
-    ];
-    if (existsSync(resolveFromProjectDirectory(".gitignore"))) {
-        args.push("--ignore-path .gitignore");
-    }
-    args.push("--write");
-    args.push("--ignore-unknown");
-    args.push("--no-error-on-unmatched-pattern");
-    try {
-        return await helpers.exec(`prettier ${args.join(" ")}`);
-    } catch (error) {
-        throw createError("prettier", error);
-    }
-};
-const checkTypes = async ()=>{
-    try {
-        return await helpers.exec("pnpm --parallel exec tsc --noEmit");
-    } catch (error) {
-        throw createError("tsc", error);
-    }
-};
-const checkCommit = async ()=>{
-    try {
-        return await helpers.exec('commitlint --extends "@commitlint/config-conventional" --edit');
-    } catch (error) {
-        throw createError("commitlint", error);
-    }
-};
-const createError = (bin, error)=>{
-    const errorMessage = `\`${bin}\` command failed.\n${String(error)}`;
-    if (error instanceof Error) {
-        error.message = errorMessage;
-        return error;
-    }
-    return new Error(errorMessage);
-};
 const turbo = async (command, options = {
     hasLiveOutput: true
 })=>{
@@ -193,26 +152,17 @@ const changeset = async (command)=>{
         throw createError("changeset", error);
     }
 };
-const TYPESCRIPT_EXTENSIONS = [
-    "ts",
-    "tsx",
-    "cts",
-    "mts"
-];
-/**
- * Extensions supported by ESLint.
- */ const ESLINT_EXTENSIONS = [
+const ESLINT_EXTENSIONS = [
     "js",
     "jsx",
     "cjs",
     "mjs",
+    "ts",
+    "tsx",
+    "cts",
+    "mts",
     "md",
-    "mdx",
-    ...TYPESCRIPT_EXTENSIONS
-];
-const PRETTIER_IGNORE_FILES = [
-    "CHANGELOG.md",
-    "pnpm-lock.yaml"
+    "mdx"
 ];
 
 const createWatchCommand = (program)=>{
@@ -266,6 +216,7 @@ const createReleaseCommand = (program)=>{
         description: "Publish package(s) to the registry"
     }).task({
         async handler () {
+            // TODO: label instead?
             helpers.message("New changelog entry\n");
             await changeset("changeset");
         },
@@ -293,12 +244,12 @@ const createInstallCommand = (program)=>{
         name: "install",
         description: "Setup initial requirements"
     }).task({
-        label: label$4("Installing `git.pre-commit` hook"),
+        label: label$4("Install `git.pre-commit` hook"),
         async handler () {
             await installGitHook("pre-commit", `${getStackCommand("fix $(git status --porcelain | awk 'BEGIN{ ORS=\" \" } { print $2 }')", false)} && git add -A`);
         }
     }).task({
-        label: label$4("Installing `git.commit-msg` hook"),
+        label: label$4("Install `git.commit-msg` hook"),
         async handler () {
             await installGitHook("commit-msg", getStackCommand("check --only commit", false));
         }
@@ -311,24 +262,59 @@ const installGitHook = async (hook, content)=>{
     return chmod(filename, "0755");
 };
 
+const fixLinter = eslint({
+    isFixMode: true
+});
+
+const PRETTIER_IGNORE_FILES = [
+    "CHANGELOG.md",
+    "pnpm-lock.yaml"
+];
+const fixFormatting = async (files)=>{
+    let prettierFiles = [];
+    if (files.length === 0) {
+        prettierFiles.push(`"**/!(${PRETTIER_IGNORE_FILES.join("|")})"`);
+    } else {
+        prettierFiles = files.filter((file)=>{
+            return !PRETTIER_IGNORE_FILES.some((filename)=>file.endsWith(filename)) && // The root `README.md` file is ignored to prevent error due to its symbolic link nature when specified explicitly as a file
+            file !== "README.md";
+        });
+        if (prettierFiles.length === 0) return Promise.resolve();
+    }
+    const args = [
+        ...prettierFiles
+    ];
+    if (existsSync(resolveFromProjectDirectory(".gitignore"))) {
+        args.push("--ignore-path .gitignore");
+    }
+    args.push("--write");
+    args.push("--ignore-unknown");
+    args.push("--no-error-on-unmatched-pattern");
+    try {
+        return await helpers.exec(`prettier ${args.join(" ")}`);
+    } catch (error) {
+        throw createError("prettier", error);
+    }
+};
+
 const createFixCommand = (program)=>{
     program.command({
         name: "fix",
         description: "Fix auto-fixable issues"
     }).task({
-        label: label$3("Preparing the project"),
+        label: label$3("Prepare the project"),
         async handler () {
             await turbo("build", {
                 hasLiveOutput: false
             });
         }
     }).task({
-        label: label$3("Fixing lints"),
+        label: label$3("Fix linter issues"),
         async handler (_, argv) {
-            await fixLints(argv.operands);
+            await fixLinter(argv.operands);
         }
     }).task({
-        label: label$3("Fixing formatting"),
+        label: label$3("Fix formatting issues"),
         async handler (_, argv) {
             await fixFormatting(argv.operands);
         }
@@ -379,7 +365,7 @@ const createCreateCommand = (program)=>{
         }
     }).task({
         key: "data",
-        label: label$2("Evaluating contextual data"),
+        label: label$2("Evaluate contextual data"),
         async handler ({ inputDescription, inputName, inputUrl }) {
             const nodeVersion = (await request.get("https://resolve-node.vercel.app/lts", "text")).replace("v", "");
             const npmVersion = (await request.get("https://registry.npmjs.org/pnpm/latest", "json")).version;
@@ -399,7 +385,7 @@ const createCreateCommand = (program)=>{
         }
     }).task({
         label ({ data }) {
-            return label$2(`Creating \`${data.projectName}\` folder`);
+            return label$2(`Create \`${data.projectName}\` folder`);
         },
         async handler ({ data }) {
             const projectPath = resolve(process.cwd(), data.projectName);
@@ -407,18 +393,18 @@ const createCreateCommand = (program)=>{
             process.chdir(projectPath);
         }
     }).task({
-        label: label$2("Initializing `git`"),
+        label: label$2("Initialize `git`"),
         async handler ({ data }) {
             await helpers.exec("git init");
             await helpers.exec(`git remote add origin ${data.projectUrl}`);
         }
     }).task({
-        label: label$2("Applying template"),
+        label: label$2("Apply template"),
         handler ({ data, inputTemplate }) {
             applyTemplate(inputTemplate, data);
         }
     }).task({
-        label: label$2("Installing dependencies"),
+        label: label$2("Install dependencies"),
         async handler ({ data }) {
             const localDevDependencies = [
                 "quickbundle",
@@ -436,7 +422,7 @@ const createCreateCommand = (program)=>{
         }
     }).task({
         key: "error",
-        label: label$2("Cleaning up"),
+        label: label$2("Clean up"),
         async handler ({ data }) {
             try {
                 // Symlink the package `README.md` file to the root project directory
@@ -518,7 +504,7 @@ const createCleanCommand = (program)=>{
         description: "Clean the project"
     }).task({
         key: "files",
-        label: label$1("Retrieving removable assets"),
+        label: label$1("Retrieve removable files"),
         async handler () {
             const cachePath = "node_modules/.cache";
             const files = await retrieveIgnoredFiles();
@@ -562,10 +548,136 @@ const PRESERVE_FILES = [
     ".turbo"
 ];
 
-const onlyValues = [
+const checkTypes = async ()=>{
+    try {
+        return await helpers.exec("pnpm --parallel exec tsc --noEmit");
+    } catch (error) {
+        throw createError("tsc", error);
+    }
+};
+
+const checkPackages = async ()=>{
+    const stdout = await helpers.exec("pnpm recursive ls --json");
+    const checkPackagesVersionMismatch = createPackagesVersionMismatchChecker();
+    const packages = JSON.parse(stdout).map((pkg)=>{
+        const pkgPath = join(pkg.path, "package.json");
+        assert(pkg.name, ()=>createPackageError(`\`${pkgPath}\` must have a name field.`));
+        const pkgContent = require(pkgPath);
+        const peerDependencies = pkgContent.peerDependencies ?? {};
+        const devDependencies = pkgContent.devDependencies ?? {};
+        const dependencies = pkgContent.dependencies ?? {};
+        return {
+            name: pkg.name,
+            dependencies,
+            devDependencies,
+            peerDependencies
+        };
+    });
+    for (const pkg of packages){
+        // Check version mismatches to guarantee a single copy for a given package in the monorepo (use case: prevent singleton-like issues with React contexts)
+        checkPackagesVersionMismatch(pkg);
+        // Check version range accordingly to our dependency guidelines (ie. dev dependencies must be pinned and dependencies must have caret)
+        checkPackagesVersionRange(pkg);
+    }
+};
+const checkPackagesVersionRange = ({ name, dependencies, devDependencies, peerDependencies })=>{
+    for (const dependencyName of Object.keys(devDependencies)){
+        const version = devDependencies[dependencyName];
+        assertVersion(version, {
+            name: dependencyName,
+            consumedBy: name
+        });
+        if (version !== "workspace:*" && !/^\d/.exec(version)) throw createPackageError(`As a dev dependency, \`${dependencyName}\` version must be fixed (or set as "workspace:*" for local packages) to reduce accidental breaking change risks due to an implicit semver upgrade.`, {
+            name: dependencyName,
+            consumedBy: name
+        });
+    }
+    const isPreReleaseVersion = (version)=>/\d+\.\d+\.\d+-(alpha|beta|experimental|next|rc).*/.exec(version);
+    const hasNoCaret = (version)=>!isPreReleaseVersion(version) && !/^\^/.exec(version);
+    for (const dependencyName of Object.keys(dependencies)){
+        const version = dependencies[dependencyName];
+        assertVersion(version, {
+            name: dependencyName,
+            consumedBy: name
+        });
+        if (version !== "workspace:^" && hasNoCaret(version)) throw createPackageError(`As a dependency, \`${dependencyName}\` version must be prefixed with a caret (or set as "workspace:^" for local packages) to optimize the size (whether of installation or bundle output) on the consumer side.`, {
+            name: dependencyName,
+            consumedBy: name
+        });
+    }
+    for (const dependencyName of Object.keys(peerDependencies)){
+        const version = peerDependencies[dependencyName];
+        assertVersion(version, {
+            name: dependencyName,
+            consumedBy: name
+        });
+        if (hasNoCaret(version)) /*
+			 * Why disallowing workspace protocol as a version resolver?
+			 * To reduce the update frequency needs consumer-side and guarantee on our side the minimum compatible version,
+			 * the best practice should be to keeping an explicit number version which represents the lowest compatible version from an API perspective.
+			 */ throw createPackageError(`As a peer dependency, \`${dependencyName}\` version must be explicit (i.e. the "workspace:^" protocol a version resolver is not allowed) and prefixed with a caret to optimize the size (whether of installation or bundle output) on the consumer side.`, {
+            name: dependencyName,
+            consumedBy: name
+        });
+    }
+};
+const createPackagesVersionMismatchChecker = ()=>{
+    const monorepoDependencies = new Map();
+    const monorepoDevDependencies = new Map();
+    const lint = (pkg, type)=>{
+        const pkgName = pkg.name;
+        const isDev = type === "development";
+        const store = isDev ? monorepoDevDependencies : monorepoDependencies;
+        const dependencies = isDev ? pkg.devDependencies : pkg.dependencies;
+        for (const dependencyName of Object.keys(dependencies)){
+            const depVersion = dependencies[dependencyName];
+            if (!depVersion) continue;
+            const storedVersion = store.get(dependencyName);
+            if (!storedVersion) {
+                store.set(dependencyName, depVersion);
+                continue;
+            }
+            const isSameMonorepoVersion = depVersion === storedVersion;
+            if (!isSameMonorepoVersion) {
+                throw createPackageError(`Mismatched versions: received version \`${depVersion}\` while others use \`${storedVersion}\`. To prevent issues with singleton-like code (React contexts, ...), please make sure to update all packages to use the same \`${dependencyName}\` version (either \`${storedVersion}\` or \`${depVersion}\`.`, {
+                    name: dependencyName,
+                    consumedBy: pkgName
+                });
+            }
+        }
+    };
+    return (pkg)=>{
+        lint(pkg, "development");
+        lint(pkg, "production");
+    };
+};
+const createPackageError = (message, context)=>{
+    return createError("stack check", !context ? message : `\`${context.name}\` consumed by \`${context.consumedBy}\` doesn't conform to our package policy.\n${message}`);
+};
+function assertVersion(version, { name, consumedBy }) {
+    assert(version, ()=>createPackageError(`\`${name}\` must have a valid version specified (current version equals to \`${String(version)}\`).`, {
+            name,
+            consumedBy
+        }));
+}
+
+const checkLinter = eslint({
+    isFixMode: false
+});
+
+const checkCommit = async ()=>{
+    try {
+        return await helpers.exec('commitlint --extends "@commitlint/config-conventional" --edit');
+    } catch (error) {
+        throw createError("commitlint", error);
+    }
+};
+
+const ONLY_VALUES = [
     "commit",
-    "lint",
-    "type"
+    "linter",
+    "packages",
+    "types"
 ];
 const createCheckCommand = (program)=>{
     program.command({
@@ -574,10 +686,10 @@ const createCheckCommand = (program)=>{
     }).option({
         key: "only",
         name: "only",
-        description: `Run only one specified task (accepted value: ${onlyValues.join(", ")})`,
+        description: `Run only one specified task (accepted value: ${ONLY_VALUES.join(", ")})`,
         defaultValue: undefined
     }).task({
-        label: label("Preparing the project"),
+        label: label("Prepare the project"),
         async handler () {
             await turbo("build", {
                 hasLiveOutput: false
@@ -587,25 +699,31 @@ const createCheckCommand = (program)=>{
             return only === "commit"; // No need to build if only commitlint is run
         }
     }).task({
-        label: label("Checking linters"),
+        label: label("Check package guidelines"),
+        async handler () {
+            await checkPackages();
+        },
+        skip: ifOnlyDefinedAndNotEqualTo("packages")
+    }).task({
+        label: label("Check linter rules"),
         async handler (_, argv) {
             const filenames = argv.operands;
-            await checkLints(filenames);
+            await checkLinter(filenames);
         },
-        skip: ifOnlyDefinedAndNotEqualTo("lint")
+        skip: ifOnlyDefinedAndNotEqualTo("linter")
     }).task({
-        label: label("Checking types"),
+        label: label("Check types"),
         async handler () {
             await checkTypes();
         },
         skip (context, argv) {
-            return ifOnlyDefinedAndNotEqualTo("type")(context) || !hasDependency("typescript") || /**
+            return ifOnlyDefinedAndNotEqualTo("types")(context) || !hasDependency("typescript") || /**
 					 * For now, skip type-checking if some files are passed down.
 					 * @see https://github.com/microsoft/TypeScript/issues/27379
 					 */ argv.operands.length > 0;
         }
     }).task({
-        label: label("Checking commit"),
+        label: label("Check commit"),
         async handler () {
             await checkCommit();
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adbayb/stack",
-  "version": "0.0.0-next-912a585",
+  "version": "0.0.0-next-ece28ab",
   "description": "My opinionated JavaScript-based toolchain",
   "publishConfig": {
     "access": "public"
@@ -42,7 +42,6 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/eslint-config-prettier": "6.11.3",
     "@types/node": "22.8.6",
     "quickbundle": "2.6.0"
   },