components-differ 1.2.2 → 1.2.4

package/README.md

@@ -1,106 +1,63 @@
-# components-differ
+## components-differ
 
-`components-differ` is a CLI that inspects a Shadcn-based project and emits a [registry-item](https://ui.shadcn.com/docs/registry/registry-item-json) compatible JSON bundle. The generated bundle captures only the delta between the project’s initial template commit and the current working tree, making it easy to distribute curated component packs or bootstrap new installations.
+CLI to generate shadcn-compatible registry items (`registry:block`) from your project.
 
-## Features
+You can use it in two ways:
 
-- ⚡️ **Quick diffing** – Scans the git history to compare the initial commit against the current state of the repository.
-- 🧠 **Alias aware** – Understands `components.json` aliases and supports projects with or without a `src/` directory.
-- 📦 **Full registry support** – Outputs files using the latest Shadcn registry types (`registry:ui`, `registry:block`, `registry:page`, `registry:file`, `registry:theme`, etc.).
-- 🧩 **Automated dependency detection** – Detects new npm dependencies/devDependencies introduced since the initial commit.
-- 🛠️ **Build+publish ready** – Includes a reproducible build step, release helpers, and Vitest coverage.
+- **Folder mode** (default): create a registry item from every file in a folder (default: current directory).
+- **Git mode** (`--git`): create a registry item from files changed since the initial git commit.
 
-## Installation
+### Install & build
 
-```bash
-pnpm install components-differ
-# or
-npm install components-differ
-# or
-yarn add components-differ
-```
-
-For one-off usage you can run the CLI with `npx`:
+From the `differ` folder:
 
 ```bash
-npx components-differ
+npm install -g components-differ
 ```
 
-## Usage
+After building, you can run the CLI with `node` or via the `components-differ` bin (if linked/installed).
 
-### 1. Prepare your project
+### Default: folder mode (current directory)
 
-1. Scaffold a new Next.js application.
-2. Install [shadcn/ui](https://ui.shadcn.com/docs/components).
-3. Commit the pristine template so that the first commit represents the baseline.
-
-You can use the built-in init helper to automate step 3:
+Run with no arguments to generate a registry item from the **current folder** (and all files it imports):
 
 ```bash
-npx components-differ --init
-```
+# from your project root – includes whole project and resolves imports
+components-differ > block.json
 
-This command wipes the current `.git` folder, initializes a new repository, creates an initial commit, and provisions a sensible `.gitignore`.
-
-### 2. Make changes
-
-Add or modify components, hooks, utilities, env files, Tailwind styles, or any other project files.
+# optional name
+components-differ -n my-block > block.json
+```
 
-### 3. Generate the registry diff
+Or target a specific folder:
 
 ```bash
-npx components-differ
+components-differ --folder src/app/dashboard -n dashboard-block > block.json
+components-differ --folder src/app/dashboard > block.json
 ```
 
-The CLI prints a JSON payload describing:
-
-- File list with appropriate registry types and targets.
-- New registry dependencies detected in your component directory.
-- Added npm dependencies and devDependencies.
+### Git mode (changed files only)
 
-You can pipe this JSON to a file or publish it to a URL and consume it with the official Shadcn CLI:
+Use `--git` when you want a registry item only from files changed since the initial commit:
 
 ```bash
-npx shadcn@latest init https://your-domain.com/registry.json
-npx shadcn@latest add https://your-domain.com/registry.json
-```
-
-## CLI Options
+# initialize a clean git history first
+components-differ --init
 
-| Flag | Description |
-| ---- | ----------- |
-| `--name <name>` | Overrides the generated registry item `name`. Defaults to the current folder name. |
-| `--init` | Re-initializes git and creates the baseline commit described above. |
+# after making changes, generate from changed files only
+components-differ --git -n my-block > block.json
+```
 
-## Development
+### Add the block locally
 
 ```bash
-pnpm install      # install dependencies
-pnpm test         # run Vitest suite (snapshot + unit tests)
-pnpm run build    # build the distributable into dist/
-pnpm run release  # build, test, and publish (requires npm auth + clean git tree)
+npx shadcn add ./block.json
 ```
 
-The project relies on git worktrees to obtain the baseline commit, so ensure your repository has at least one commit before running the CLI in development.
-
-## How It Works
-
-1. **Worktree clone** – `scanForAlteredFiles` creates a temporary git worktree of the initial commit.
-2. **File classification** – `parseFilePath` maps files to Shadcn registry types (page, ui, block, theme, style, lib, hook, file, item) while honoring `components.json` aliases and `src/` directory layouts.
-3. **Manifest parsing** – `readComponentsManifest` reads alias definitions and determines whether the project uses `src/`.
-4. **Dependency diff** – `createDiff` compares the current `package.json` with the baseline to capture dependency changes.
-5. **Output assembly** – Files, registry dependencies, metadata, Tailwind placeholders, and CSS variables are assembled into a registry item schema.
-
-## Releasing
-
-1. Update `package.json` version (use `pnpm node ./scripts/bump-version.mjs` for a patch bump).
-2. Ensure the working tree is clean.
-3. Run `pnpm run release` to build, test, and publish to npm.
-
-## Contributing
-
-Pull requests are welcome! Please accompany feature changes with unit tests or snapshot updates as appropriate. If you’re unsure where files are classified or need new registry types, check `src/parse-file-path.mjs` and corresponding tests under `tests/tests`.
+### Options summary
 
-## License
+- **`--init`**: initialize a clean git repo and first commit (for use with `--git` later).
+- **`-n, --name <name>`**: registry item name; defaults to current (or folder) name.
+- **`-f, --folder <folder>`**: folder to include (default: current directory). Ignored if `--git` is set.
+- **`--git`**: use git mode (only files changed since initial commit).
 
-MIT © Components Host

package/dist/components.js

@@ -0,0 +1,130 @@
+import path from "node:path";
+import fs from "node:fs";
+const WHITELISTED_COMPONENTS = [
+    "accordion",
+    "alert",
+    "alert-dialog",
+    "aspect-ratio",
+    "avatar",
+    "badge",
+    "breadcrumb",
+    "button",
+    "button-group",
+    "calendar",
+    "card",
+    "carousel",
+    "chart",
+    "checkbox",
+    "collapsible",
+    "combobox",
+    "command",
+    "context-menu",
+    "data-table",
+    "date-picker",
+    "dialog",
+    "drawer",
+    "dropdown-menu",
+    "empty",
+    "field",
+    "form",
+    "hover-card",
+    "input",
+    "input-group",
+    "input-otp",
+    "item",
+    "kbd",
+    "label",
+    "menubar",
+    "native-select",
+    "navigation-menu",
+    "pagination",
+    "popover",
+    "progress",
+    "radio-group",
+    "resizable",
+    "scroll-area",
+    "select",
+    "separator",
+    "sheet",
+    "sidebar",
+    "skeleton",
+    "slider",
+    "sonner",
+    "spinner",
+    "switch",
+    "table",
+    "tabs",
+    "textarea",
+    "toast",
+    "toggle",
+    "toggle-group",
+    "tooltip",
+    "typography",
+];
+function findComponentsJson(startDir) {
+    let currentDir = startDir;
+    while (true) {
+        const manifestPath = path.join(currentDir, "components.json");
+        if (fs.existsSync(manifestPath)) {
+            return manifestPath;
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    return null;
+}
+export function findComponentFiles(config, originalFiles) {
+    const registryDependencies = [];
+    const compDir = config.ui.replace("@/", config.isSrcDir ? "src/" : "");
+    const registriesConfig = config.registries ?? {};
+    const registryNamespaces = Object.keys(registriesConfig);
+    const defaultNamespace = registryNamespaces.find((name) => name === "@shadcn") ??
+        registryNamespaces[0] ??
+        null;
+    for (const { path: filePath } of originalFiles) {
+        if (filePath.startsWith(compDir)) {
+            const fileExtension = path.extname(filePath);
+            const fileName = path.basename(filePath, fileExtension);
+            if ((fileExtension === ".tsx" || fileExtension === ".jsx") &&
+                WHITELISTED_COMPONENTS.includes(fileName)) {
+                const baseName = path.basename(filePath, fileExtension);
+                const dependencyName = defaultNamespace
+                    ? `${defaultNamespace}/${baseName}`
+                    : baseName;
+                registryDependencies.push(dependencyName);
+            }
+        }
+    }
+    return registryDependencies;
+}
+export function readComponentsManifest(dir) {
+    const manifestPath = findComponentsJson(dir);
+    if (!manifestPath) {
+        console.error("Components manifest (components.json) not found");
+        process.exit(1);
+    }
+    const json = JSON.parse(fs.readFileSync(manifestPath, "utf-8"));
+    return {
+        ...json.aliases,
+        registries: json.registries ?? {},
+    };
+}
+export function getAliasedPaths(config) {
+    return [
+        config.components.replace("@/", ""),
+        config.utils.replace("@/", ""),
+        config.ui.replace("@/", ""),
+        config.lib.replace("@/", ""),
+        config.hooks.replace("@/", ""),
+    ];
+}
+export function isBuiltinComponent(config, filePath) {
+    if (filePath.startsWith(config.ui.replace("@/", ""))) {
+        const component = path.basename(filePath, path.extname(filePath));
+        return WHITELISTED_COMPONENTS.includes(component);
+    }
+    return false;
+}

package/dist/create-diff.js

@@ -0,0 +1,75 @@
+import { findComponentFiles, getAliasedPaths, } from "./components.js";
+import { parseFilePath } from "./parse-file-path.js";
+import { extractImportedPackages } from "./extract-imports.js";
+function addFile(output, config, inSrcDir, relativeFilePath, content) {
+    output.files.push(parseFilePath(inSrcDir, config, `./${relativeFilePath}`, content));
+}
+function addDependencies(output, _initialPackageContents, currentPackageContents, usedPackages) {
+    const currentPackageJson = JSON.parse(currentPackageContents);
+    const currentDependencies = currentPackageJson.dependencies ?? {};
+    const currentDevDependencies = currentPackageJson.devDependencies ?? {};
+    const shadcnNamespaces = new Set(output.registryDependencies
+        .map((dep) => dep.split("/")[0])
+        .filter((ns) => ns === "@shadcn"));
+    const shouldKeepDep = (dep) => {
+        if (!usedPackages.has(dep))
+            return false;
+        if (!shadcnNamespaces.size)
+            return true;
+        if (dep === "shadcn/ui")
+            return false;
+        for (const ns of shadcnNamespaces) {
+            if (dep === ns || dep === `${ns}/ui`) {
+                return false;
+            }
+        }
+        return true;
+    };
+    // Only include packages that are actually imported in the registry item files
+    // (and exist in package.json so we know dep vs devDep). No other deps.
+    output.dependencies = Object.keys(currentDependencies).filter(shouldKeepDep);
+    output.devDependencies = Object.keys(currentDevDependencies).filter(shouldKeepDep);
+}
+function scanWithSrcDir(output, config, alteredFiles) {
+    for (const { path, content } of alteredFiles) {
+        if (path.startsWith("src/")) {
+            addFile(output, config, true, path.replace("src/", ""), content);
+        }
+        else {
+            addFile(output, config, false, path, content);
+        }
+    }
+}
+function isInAppDir(filePath) {
+    return filePath.startsWith("app/");
+}
+function scanWithoutSrcDir(output, config, alteredFiles) {
+    const aliasedPaths = getAliasedPaths(config);
+    for (const { path, content } of alteredFiles) {
+        const inSrcDir = aliasedPaths.includes(path) || isInAppDir(path);
+        addFile(output, config, inSrcDir, path, content);
+    }
+}
+export function createDiff({ name, config, alteredFiles, specificFiles, currentFiles, currentPackageJson, }) {
+    const output = {
+        name,
+        type: "registry:block",
+        dependencies: [],
+        devDependencies: [],
+        registryDependencies: [],
+        files: [],
+        tailwind: {},
+        cssVars: {},
+        meta: {},
+    };
+    if (config.isSrcDir) {
+        scanWithSrcDir(output, config, alteredFiles);
+    }
+    else {
+        scanWithoutSrcDir(output, config, alteredFiles);
+    }
+    output.registryDependencies = findComponentFiles(config, currentFiles);
+    const usedPackages = extractImportedPackages(alteredFiles);
+    addDependencies(output, specificFiles["./package.json"], currentPackageJson, usedPackages);
+    return output;
+}

package/dist/extract-imports.js

@@ -0,0 +1,90 @@
+/**
+ * Extract npm package names from import/require statements in source code.
+ * Used to include only dependencies that are actually used by the registry item files.
+ */
+/**
+ * Returns the root package name for a specifier. Handles scoped packages and subpaths.
+ * - "react" -> "react"
+ * - "lodash/merge" -> "lodash"
+ * - "@scope/pkg" -> "@scope/pkg"
+ * - "@scope/pkg/sub" -> "@scope/pkg"
+ */
+function specifierToPackageName(specifier) {
+    const s = specifier.trim();
+    if (!s)
+        return null;
+    // Node / bundler builtins
+    if (s.startsWith("node:") || s === "node")
+        return null;
+    // Relative imports – not packages
+    if (s.startsWith(".") || s.startsWith("/"))
+        return null;
+    // Common path aliases (not package names)
+    if (s.startsWith("@/") || s.startsWith("~/") || s.startsWith("#"))
+        return null;
+    // Scoped package: @scope/pkg or @scope/pkg/subpath
+    if (s.startsWith("@")) {
+        const firstSlash = s.indexOf("/");
+        if (firstSlash === -1)
+            return s;
+        const secondSlash = s.indexOf("/", firstSlash + 1);
+        return secondSlash === -1 ? s : s.slice(0, secondSlash);
+    }
+    // Normal package or subpath
+    const slash = s.indexOf("/");
+    return slash === -1 ? s : s.slice(0, slash);
+}
+const RE_IMPORT = /(?:import\s+(?:(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+)?|import\s*)['"]([^'"]+)['"]|require\s*\(\s*['"]([^'"]+)['"]\s*\)|import\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+/**
+ * Collect all package names that are imported or required in the given file content.
+ */
+function extractFromContent(content) {
+    const packages = new Set();
+    let m;
+    RE_IMPORT.lastIndex = 0;
+    while ((m = RE_IMPORT.exec(content)) !== null) {
+        const specifier = (m[1] ?? m[2] ?? m[3]) ?? "";
+        const pkg = specifierToPackageName(specifier);
+        if (pkg)
+            packages.add(pkg);
+    }
+    return packages;
+}
+/**
+ * Collect all package names imported by any of the given files (by their content).
+ */
+export function extractImportedPackages(files) {
+    const all = new Set();
+    for (const { content } of files) {
+        for (const pkg of extractFromContent(content)) {
+            all.add(pkg);
+        }
+    }
+    return all;
+}
+/** True if the import specifier refers to a project file (relative or path alias), not npm. */
+export function isPathSpecifier(specifier) {
+    const s = specifier.trim();
+    if (!s || s.startsWith("node:"))
+        return false;
+    if (s.startsWith(".") || s.startsWith("/"))
+        return true;
+    if (s.startsWith("@/") || s.startsWith("~/") || s.startsWith("#"))
+        return true;
+    return false;
+}
+/**
+ * Extract all import/require specifiers that are project paths (relative or alias)
+ * from file content. Used to pull in imported files into the registry.
+ */
+export function extractPathSpecifiers(content) {
+    const out = [];
+    let m;
+    RE_IMPORT.lastIndex = 0;
+    while ((m = RE_IMPORT.exec(content)) !== null) {
+        const specifier = (m[1] ?? m[2] ?? m[3]) ?? "";
+        if (isPathSpecifier(specifier))
+            out.push(specifier);
+    }
+    return out;
+}

package/dist/git.js

@@ -0,0 +1,117 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import ignore from "ignore";
+const INITIAL_DIR = "_initial";
+const EXCLUDE_DIRS = [
+    "node_modules",
+    "dist",
+    "fonts",
+    "build",
+    "public",
+    "static",
+    ".next",
+    ".git",
+    INITIAL_DIR,
+];
+const EXCLUDE_FILES = [
+    ".DS_Store",
+    "next-env.d.ts",
+    "package-lock.json",
+    "yarn.lock",
+    "pnpm-lock.yaml",
+    "bun.lockb",
+    "package.json",
+    "tailwind.config.ts",
+    "tailwind.config.js",
+    "components.json",
+    "favicon.ico",
+];
+function cloneInitialCommit() {
+    deleteInitialDir();
+    try {
+        const initialCommit = execSync("git rev-list --max-parents=0 HEAD")
+            .toString()
+            .trim();
+        execSync(`git worktree add -f ${INITIAL_DIR} ${initialCommit}`, {
+            stdio: "ignore",
+        });
+    }
+    catch (error) {
+        console.error("Error cloning initial commit:", error.message);
+        process.exit(1);
+    }
+}
+function deleteInitialDir() {
+    if (fs.existsSync(INITIAL_DIR)) {
+        fs.rmSync(INITIAL_DIR, { recursive: true, force: true });
+        try {
+            execSync("git worktree prune", { stdio: "ignore" });
+        }
+        catch (error) {
+            console.error("Error pruning git worktree:", error.message);
+        }
+    }
+}
+function checkIfFileIsChanged(relativeFilePath) {
+    const initialFilePath = path.join(INITIAL_DIR, relativeFilePath);
+    const fullPath = path.join(process.cwd(), relativeFilePath);
+    if (!fs.existsSync(initialFilePath)) {
+        return true;
+    }
+    const currentContent = fs.readFileSync(fullPath, "utf-8");
+    const initialContent = fs.readFileSync(initialFilePath, "utf-8");
+    return currentContent !== initialContent;
+}
+export function scanForFiles(startDir, checkFile = false) {
+    const foundFiles = [];
+    let ignorer = () => false;
+    const gitignorePath = path.join(startDir, ".gitignore");
+    if (fs.existsSync(gitignorePath)) {
+        const gitIgnore = ignore().add(fs.readFileSync(gitignorePath).toString());
+        ignorer = (relativeFilePath) => gitIgnore.ignores(relativeFilePath);
+    }
+    function scanDirectory(dir, relativePath = "") {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            const relativeFilePath = path.join(relativePath, entry.name);
+            if (entry.isDirectory()) {
+                if (!EXCLUDE_DIRS.includes(entry.name)) {
+                    scanDirectory(path.join(dir, entry.name), relativeFilePath);
+                }
+            }
+            else if (!checkFile ||
+                (checkFile && checkIfFileIsChanged(relativeFilePath))) {
+                if (!EXCLUDE_FILES.includes(entry.name) &&
+                    !ignorer(relativeFilePath)) {
+                    foundFiles.push({
+                        path: relativeFilePath,
+                        content: fs.readFileSync(fullPath, "utf-8"),
+                    });
+                }
+            }
+        }
+    }
+    scanDirectory(startDir);
+    return foundFiles.sort((a, b) => a.path.localeCompare(b.path));
+}
+export function scanForAlteredFiles(specificFilesToReturn = []) {
+    cloneInitialCommit();
+    const alteredFiles = scanForFiles(process.cwd(), true);
+    const specificFiles = specificFilesToReturn.reduce((out, file) => {
+        const fullPath = path.join(process.cwd(), INITIAL_DIR, file);
+        out[file] = fs.existsSync(fullPath)
+            ? fs.readFileSync(fullPath, "utf-8")
+            : "";
+        return out;
+    }, {});
+    deleteInitialDir();
+    return {
+        alteredFiles,
+        specificFiles,
+    };
+}
+export function hasSrcDir(dir) {
+    return fs.existsSync(path.join(dir, "src"));
+}

package/dist/index.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { execSync } from "node:child_process";
+import { program } from "commander";
+import { scanForAlteredFiles, scanForFiles, hasSrcDir, } from "./git.js";
+import { readComponentsManifest } from "./components.js";
+import { createDiff } from "./create-diff.js";
+import { expandIncludedFiles } from "./resolve-imports.js";
+function runCommand(command) {
+    try {
+        execSync(command, { stdio: "inherit" });
+    }
+    catch (error) {
+        console.error(`Failed to execute command: ${command}`);
+        process.exit(1);
+    }
+}
+function ensureGitignore() {
+    const gitignorePath = path.join(process.cwd(), ".gitignore");
+    if (!fs.existsSync(gitignorePath)) {
+        const content = `
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+`;
+        fs.writeFileSync(gitignorePath, content, "utf8");
+    }
+}
+function main() {
+    program
+        .option("-n, --name <name>")
+        .option("--init")
+        .option("-f, --folder <folder>", "folder to include (default: current directory)")
+        .option("--git", "use git mode: only files changed since initial commit");
+    program.parse();
+    const options = program.opts();
+    if (options.init) {
+        // Initialize a clean git repository for the current component
+        if (process.platform === "win32") {
+            runCommand('rmdir /s /q .git && git init && git add . && git commit -m "Initial commit"');
+        }
+        else {
+            runCommand('rm -fr .git && git init && git add . && git commit -m "Initial commit"');
+        }
+        ensureGitignore();
+        return;
+    }
+    const useFolderMode = !options.git;
+    const folderOpt = options.folder ?? (useFolderMode ? "." : undefined);
+    const baseName = folderOpt != null
+        ? path.basename(path.resolve(process.cwd(), folderOpt))
+        : path.basename(process.cwd());
+    const name = options.name || baseName;
+    let alteredFiles;
+    let specificFiles;
+    if (useFolderMode && folderOpt != null) {
+        const folderPath = path.resolve(process.cwd(), folderOpt);
+        if (!fs.existsSync(folderPath) || !fs.statSync(folderPath).isDirectory()) {
+            console.error(`Folder path is not a directory: ${folderOpt}`);
+            process.exit(1);
+        }
+        const folderPrefix = path
+            .relative(process.cwd(), folderPath)
+            .replace(/\\/g, "/")
+            .replace(/^\.\//, "");
+        const allFiles = scanForFiles(process.cwd());
+        alteredFiles = allFiles.filter(({ path: filePath }) => {
+            const normalized = filePath.replace(/\\/g, "/");
+            return (normalized === folderPrefix ||
+                normalized.startsWith(`${folderPrefix}/`));
+        });
+        specificFiles = {
+            "./package.json": "{}",
+        };
+    }
+    else {
+        const result = scanForAlteredFiles(["./package.json"]);
+        alteredFiles = result.alteredFiles;
+        specificFiles = result.specificFiles;
+    }
+    const currentFiles = scanForFiles(process.cwd());
+    const currentPackageJson = fs.readFileSync("./package.json", "utf-8");
+    const config = readComponentsManifest(process.cwd());
+    config.isSrcDir = hasSrcDir(process.cwd());
+    // Recursively add any project file imported by the included files so the
+    // registry item is self-contained (no "component not found").
+    alteredFiles = expandIncludedFiles(alteredFiles, currentFiles, config);
+    const output = createDiff({
+        name,
+        config,
+        alteredFiles,
+        currentFiles,
+        specificFiles,
+        currentPackageJson,
+    });
+    // Emit a complete registry:block JSON object suitable for local file support
+    // (e.g. `npx shadcn add ./block.json`)
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(output, null, 2));
+}
+main();