@comity-dev/package-tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Filippo Bovo and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin/comity-normalize-exports.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * comity-normalize-exports — canonical export declaration normalizer for Comity packages.
+ *
+ * Usage:
+ *   comity-normalize-exports [options]
+ *
+ * Options:
+ *   --help, -h     Show this help
+ *   --check        Check mode - exit with code 1 if changes needed
+ *
+ * The tool processes all index.ts files in packages/ and normalizes
+ * export declaration ordering (type exports first, then runtime exports,
+ * both sorted alphabetically by module specifier).
+ */
+export {};

package/dist/bin/comity-normalize-exports.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * comity-normalize-exports — canonical export declaration normalizer for Comity packages.
+ *
+ * Usage:
+ *   comity-normalize-exports [options]
+ *
+ * Options:
+ *   --help, -h     Show this help
+ *   --check        Check mode - exit with code 1 if changes needed
+ *
+ * The tool processes all index.ts files in packages/ and normalizes
+ * export declaration ordering (type exports first, then runtime exports,
+ * both sorted alphabetically by module specifier).
+ */
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as ts from "typescript";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, "..", "..", "..", ".."); // monorepo root (from dist/bin/)
+const PACKAGES_DIR = join(REPO_ROOT, "packages");
+const EXCLUDED_DIRS = new Set([
+    "node_modules",
+    "dist",
+    ".turbo",
+    "coverage",
+    "__tests__",
+    "__mocks__",
+]);
+const EXCLUDED_PACKAGES = new Set([]);
+function shouldProcessFile(filePath) {
+    const relPath = relative(REPO_ROOT, filePath);
+    const parts = relPath.split("/");
+    for (const part of parts) {
+        if (EXCLUDED_DIRS.has(part))
+            return false;
+    }
+    return true;
+}
+function getPackageName(filePath) {
+    const relPath = relative(PACKAGES_DIR, filePath);
+    const pkgDir = relPath.split("/")[0];
+    return `@comity/${pkgDir}`;
+}
+function isExcludedPackage(pkgName) {
+    return EXCLUDED_PACKAGES.has(pkgName);
+}
+function isSetupIndex(filePath) {
+    return filePath.includes("/src/setup/index.ts");
+}
+async function findTypeScriptFiles(dir) {
+    const files = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (!shouldProcessFile(fullPath))
+            continue;
+        if (entry.isDirectory()) {
+            files.push(...(await findTypeScriptFiles(fullPath)));
+        }
+        else if (entry.name === "index.ts" && fullPath.includes("/src/")) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function getSourceFile(filePath, content) {
+    return ts.createSourceFile(filePath, content, ts.ScriptTarget.Latest, true);
+}
+function getExportDeclarations(sourceFile) {
+    const exports = [];
+    function visit(node) {
+        if (ts.isExportDeclaration(node)) {
+            exports.push(node);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return exports;
+}
+function getExportInfo(exportDecl, sourceFile) {
+    const text = exportDecl.getText(sourceFile);
+    const isTypeOnly = exportDecl.isTypeOnly === true;
+    const moduleSpecifier = exportDecl.moduleSpecifier?.getText(sourceFile) ?? "";
+    const start = exportDecl.getStart(sourceFile);
+    const end = exportDecl.getEnd();
+    return {
+        text,
+        isTypeOnly,
+        moduleSpecifier: moduleSpecifier.replace(/^["']|["']$/g, ""),
+        start,
+        end,
+        node: exportDecl,
+    };
+}
+function getSortKey(info) {
+    return info.moduleSpecifier || "zzz-local";
+}
+function normalizeExports(content, sourceFile) {
+    const exportDecls = getExportDeclarations(sourceFile);
+    if (exportDecls.length === 0)
+        return content;
+    const exportInfos = exportDecls.map((decl) => getExportInfo(decl, sourceFile));
+    const typeExports = exportInfos.filter((info) => info.isTypeOnly);
+    const runtimeExports = exportInfos.filter((info) => !info.isTypeOnly);
+    if (typeExports.length === 0 && runtimeExports.length === 0) {
+        return content;
+    }
+    // exportInfos is guaranteed non-empty here because we checked above
+    const firstExport = exportInfos[0];
+    const lastExport = exportInfos[exportInfos.length - 1];
+    typeExports.sort((a, b) => getSortKey(a).localeCompare(getSortKey(b)));
+    runtimeExports.sort((a, b) => getSortKey(a).localeCompare(getSortKey(b)));
+    const lines = content.split(/\r?\n/);
+    const startLine = sourceFile.getLineAndCharacterOfPosition(firstExport.start).line;
+    const endLine = sourceFile.getLineAndCharacterOfPosition(lastExport.end).line;
+    const beforeExports = lines.slice(0, startLine);
+    const afterExports = lines.slice(endLine + 1);
+    const newExportLines = [];
+    if (typeExports.length > 0) {
+        newExportLines.push(...typeExports.map((info) => info.text));
+    }
+    if (typeExports.length > 0 && runtimeExports.length > 0) {
+        newExportLines.push("");
+    }
+    if (runtimeExports.length > 0) {
+        newExportLines.push(...runtimeExports.map((info) => info.text));
+    }
+    const newContent = [...beforeExports, ...newExportLines, ...afterExports].join("\n");
+    return newContent;
+}
+async function processFile(filePath) {
+    const content = await readFile(filePath, "utf8");
+    const sourceFile = getSourceFile(filePath, content);
+    const newContent = normalizeExports(content, sourceFile);
+    return { filePath, original: content, normalized: newContent, changed: content !== newContent };
+}
+function printHelp() {
+    console.log(`comity-normalize-exports — canonical export declaration normalizer for Comity packages
+
+Usage:
+  comity-normalize-exports [options]
+
+Options:
+  --help, -h     Show this help
+  --check        Check mode - exit with code 1 if changes needed
+
+The tool processes all index.ts files in packages/ and normalizes
+export declaration ordering (type exports first, then runtime exports,
+both sorted alphabetically by module specifier).`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const checkMode = args.includes("--check") || args.includes("-c");
+    const helpMode = args.includes("--help") || args.includes("-h");
+    if (helpMode) {
+        printHelp();
+        process.exit(0);
+    }
+    const files = await findTypeScriptFiles(PACKAGES_DIR);
+    console.log(`Found ${files.length} index.ts files to process`);
+    let hasChanges = false;
+    const changedFiles = [];
+    for (const filePath of files) {
+        if (!shouldProcessFile(filePath))
+            continue;
+        const pkgName = getPackageName(filePath);
+        if (isExcludedPackage(pkgName))
+            continue;
+        const result = await processFile(filePath);
+        if (result.changed) {
+            hasChanges = true;
+            changedFiles.push({ path: result.filePath, pkg: pkgName });
+            if (!checkMode) {
+                await writeFile(result.filePath, result.normalized, "utf8");
+                console.log(`Normalized: ${relative(REPO_ROOT, result.filePath)}`);
+            }
+            else {
+                console.log(`Would normalize: ${relative(REPO_ROOT, result.filePath)}`);
+            }
+        }
+    }
+    if (checkMode) {
+        if (hasChanges) {
+            console.log(`\n${changedFiles.length} file(s) would be changed:`);
+            for (const f of changedFiles) {
+                console.log(`  - ${f.pkg}: ${relative(REPO_ROOT, f.path)}`);
+            }
+            process.exit(1);
+        }
+        else {
+            console.log("All export declarations are already normalized.");
+            process.exit(0);
+        }
+    }
+    else {
+        if (hasChanges) {
+            console.log(`\nNormalized ${changedFiles.length} file(s).`);
+        }
+        else {
+            console.log("All export declarations are already normalized.");
+        }
+    }
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/bin/comity-normalize-package-json.d.ts

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * comity-normalize-package-json — canonical key-order normalizer for `package.json`
+ * files in a Comity workspace.
+ *
+ * Usage:
+ *   comity-normalize-package-json [options]
+ *
+ * Options:
+ *   --help, -h                  Show this help
+ *   --check                     Check mode - exit with code 1 if changes needed
+ *   --packages-dir <dir>        Directory containing packages (default: packages)
+ *   --package-pattern <re>      Regex pattern for package names (default: ^@comity/)
+ *   --repo-root <dir>           Repository root (default: auto-detected)
+ *
+ * Exit codes:
+ *   0 - Success (no changes needed in check mode, or changes applied)
+ *   1 - Changes needed (check mode) or error
+ */
+export {};

package/dist/bin/comity-normalize-package-json.js

@@ -0,0 +1,303 @@
+#!/usr/bin/env node
+/**
+ * comity-normalize-package-json — canonical key-order normalizer for `package.json`
+ * files in a Comity workspace.
+ *
+ * Usage:
+ *   comity-normalize-package-json [options]
+ *
+ * Options:
+ *   --help, -h                  Show this help
+ *   --check                     Check mode - exit with code 1 if changes needed
+ *   --packages-dir <dir>        Directory containing packages (default: packages)
+ *   --package-pattern <re>      Regex pattern for package names (default: ^@comity/)
+ *   --repo-root <dir>           Repository root (default: auto-detected)
+ *
+ * Exit codes:
+ *   0 - Success (no changes needed in check mode, or changes applied)
+ *   1 - Changes needed (check mode) or error
+ */
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+const CANONICAL_TOP_LEVEL_ORDER = [
+    "name",
+    "version",
+    "description",
+    "type",
+    "private",
+    "author",
+    "license",
+    "comity",
+    "homepage",
+    "repository",
+    "bugs",
+    "engines",
+    "keywords",
+    "scripts",
+    "files",
+    "main",
+    "module",
+    "types",
+    "exports",
+    "typesVersions",
+    "publishConfig",
+    "sideEffects",
+    "peerDependencies",
+    "dependencies",
+    "optionalDependencies",
+    "devDependencies",
+];
+const CANONICAL_SCRIPTS_ORDER = ["build", "prepublishOnly", "dev", "test", "type-check", "lint"];
+const CANONICAL_KEYWORD_PRIORITY = ["comity", "comityjs"];
+function sortDependencies(deps) {
+    if (!deps || typeof deps !== "object")
+        return {};
+    const comity = {};
+    const scoped = {};
+    const unscoped = {};
+    for (const [key, value] of Object.entries(deps)) {
+        if (key.startsWith("@comity/")) {
+            comity[key] = value;
+        }
+        else if (key.startsWith("@")) {
+            scoped[key] = value;
+        }
+        else {
+            unscoped[key] = value;
+        }
+    }
+    const sortObj = (obj) => Object.fromEntries(Object.entries(obj).sort(([a], [b]) => a.localeCompare(b)));
+    return { ...sortObj(comity), ...sortObj(scoped), ...sortObj(unscoped) };
+}
+function sortKeywords(keywords) {
+    if (!Array.isArray(keywords))
+        return [];
+    const priority = new Set(CANONICAL_KEYWORD_PRIORITY);
+    const priorityKeywords = [];
+    const otherKeywords = [];
+    for (const kw of keywords) {
+        if (priority.has(kw)) {
+            priorityKeywords.push(kw);
+        }
+        else {
+            otherKeywords.push(kw);
+        }
+    }
+    return [...priorityKeywords.sort(), ...otherKeywords.sort()];
+}
+function sortExports(exports) {
+    if (!exports || typeof exports !== "object")
+        return {};
+    const result = {};
+    if (exports["."] !== undefined) {
+        result["."] = exports["."];
+    }
+    const subpaths = Object.keys(exports)
+        .filter((k) => k !== "." && k !== "./package.json")
+        .sort();
+    for (const subpath of subpaths) {
+        result[subpath] = exports[subpath];
+    }
+    if (exports["./package.json"] !== undefined) {
+        result["./package.json"] = exports["./package.json"];
+    }
+    for (const [key, value] of Object.entries(result)) {
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            const conditionOrder = ["import", "require", "types", "default"];
+            const sortedConditions = {};
+            const valueObj = value;
+            for (const cond of conditionOrder) {
+                if (valueObj[cond] !== undefined) {
+                    sortedConditions[cond] = valueObj[cond];
+                }
+            }
+            for (const [cond, val] of Object.entries(valueObj)) {
+                if (!conditionOrder.includes(cond)) {
+                    sortedConditions[cond] = val;
+                }
+            }
+            result[key] = sortedConditions;
+        }
+    }
+    return result;
+}
+function sortTypesVersions(typesVersions) {
+    if (!typesVersions || typeof typesVersions !== "object")
+        return {};
+    const result = {};
+    for (const [version, mapping] of Object.entries(typesVersions)) {
+        if (mapping && typeof mapping === "object") {
+            result[version] = Object.fromEntries(Object.entries(mapping).sort(([a], [b]) => a.localeCompare(b)));
+        }
+    }
+    return result;
+}
+function sortScripts(scripts) {
+    if (!scripts || typeof scripts !== "object")
+        return {};
+    const result = {};
+    for (const script of CANONICAL_SCRIPTS_ORDER) {
+        if (scripts[script] !== undefined) {
+            result[script] = scripts[script];
+        }
+    }
+    for (const [key, value] of Object.entries(scripts)) {
+        if (!CANONICAL_SCRIPTS_ORDER.includes(key)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function normalizePackageJson(pkgJson) {
+    const normalized = {};
+    for (const key of CANONICAL_TOP_LEVEL_ORDER) {
+        if (pkgJson[key] !== undefined) {
+            let value = pkgJson[key];
+            if (["peerDependencies", "dependencies", "optionalDependencies", "devDependencies"].includes(key)) {
+                value = sortDependencies(value);
+            }
+            else if (key === "keywords") {
+                value = sortKeywords(value);
+            }
+            else if (key === "exports") {
+                value = sortExports(value);
+            }
+            else if (key === "typesVersions") {
+                value = sortTypesVersions(value);
+            }
+            else if (key === "scripts") {
+                value = sortScripts(value);
+            }
+            normalized[key] = value;
+        }
+    }
+    for (const [key, value] of Object.entries(pkgJson)) {
+        if (!CANONICAL_TOP_LEVEL_ORDER.includes(key)) {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+async function readPackageJson(pkgPath) {
+    const content = await readFile(pkgPath, "utf8");
+    return JSON.parse(content);
+}
+async function writePackageJson(pkgPath, pkgJson) {
+    const content = JSON.stringify(pkgJson, null, 2) + "\n";
+    await writeFile(pkgPath, content, "utf8");
+}
+async function findPackageJsons(packagesDir, packagePattern) {
+    const packageJsons = [];
+    let entries;
+    try {
+        entries = await readdir(packagesDir, { withFileTypes: true });
+    }
+    catch {
+        return packageJsons;
+    }
+    const regex = new RegExp(packagePattern);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const pkgPath = join(packagesDir, entry.name, "package.json");
+        try {
+            const pkgJson = await readPackageJson(pkgPath);
+            const pkgName = pkgJson["name"];
+            if (pkgName && regex.test(pkgName)) {
+                packageJsons.push({ path: pkgPath, name: pkgName, json: pkgJson });
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return packageJsons;
+}
+function printHelp() {
+    console.log(`Usage: comity-normalize-package-json [options]
+
+Options:
+  --packages-dir <dir>    Directory containing packages (default: packages)
+  --package-pattern <re>  Regex pattern for package names (default: ^@comity/)
+  --repo-root <dir>       Repository root (default: auto-detected)
+  --check                 Check mode - exit with code 1 if changes needed
+  --help                  Show this help
+
+Exit codes:
+  0 - Success (no changes needed in check mode, or changes applied)
+  1 - Changes needed (check mode) or error`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        printHelp();
+        process.exit(0);
+    }
+    const checkMode = args.includes("--check");
+    let packagesDir = "packages";
+    const packagesDirIndex = args.indexOf("--packages-dir");
+    if (packagesDirIndex !== -1 && packagesDirIndex + 1 < args.length) {
+        const val = args[packagesDirIndex + 1];
+        if (val)
+            packagesDir = val;
+    }
+    let packagePattern = "^@comity/";
+    const packagePatternIndex = args.indexOf("--package-pattern");
+    if (packagePatternIndex !== -1 && packagePatternIndex + 1 < args.length) {
+        const val = args[packagePatternIndex + 1];
+        if (val)
+            packagePattern = val;
+    }
+    let repoRoot = process.cwd();
+    const repoRootIndex = args.indexOf("--repo-root");
+    if (repoRootIndex !== -1 && repoRootIndex + 1 < args.length) {
+        const val = args[repoRootIndex + 1];
+        if (val)
+            repoRoot = resolve(val);
+    }
+    const resolvedPackagesDir = resolve(repoRoot, packagesDir);
+    const packageJsons = await findPackageJsons(resolvedPackagesDir, packagePattern);
+    let hasChanges = false;
+    const changedFiles = [];
+    for (const { path, name, json } of packageJsons) {
+        const normalized = normalizePackageJson(json);
+        const originalContent = JSON.stringify(json, null, 2) + "\n";
+        const normalizedContent = JSON.stringify(normalized, null, 2) + "\n";
+        if (originalContent !== normalizedContent) {
+            hasChanges = true;
+            changedFiles.push(name);
+            if (!checkMode) {
+                await writePackageJson(path, normalized);
+                console.log(`Normalized: ${name}`);
+            }
+            else {
+                console.log(`Would normalize: ${name}`);
+            }
+        }
+    }
+    if (checkMode) {
+        if (hasChanges) {
+            console.log(`\n${changedFiles.length} package.json file(s) would be changed:`);
+            for (const name of changedFiles) {
+                console.log(`  - ${name}`);
+            }
+            process.exit(1);
+        }
+        else {
+            console.log("All package.json files are already normalized.");
+            process.exit(0);
+        }
+    }
+    else {
+        if (hasChanges) {
+            console.log(`\nNormalized ${changedFiles.length} package.json file(s).`);
+        }
+        else {
+            console.log("All package.json files are already normalized.");
+        }
+    }
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @comity-dev/package-tools — Comity package metadata tooling.
+ *
+ * This package provides:
+ * - `comity-normalize-exports` binary for normalizing TypeScript export declarations
+ * - `comity-normalize-package-json` binary for normalizing package.json key order
+ *
+ * The CLI entry points are at `src/bin/comity-normalize-exports.ts` and `src/bin/comity-normalize-package-json.ts`.
+ */ 

package/dist/index.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * @comity-dev/package-tools — Comity package metadata tooling.
+ *
+ * This package provides:
+ * - `comity-normalize-exports` binary for normalizing TypeScript export declarations
+ * - `comity-normalize-package-json` binary for normalizing package.json key order
+ *
+ * The CLI entry points are at `src/bin/comity-normalize-exports.ts` and `src/bin/comity-normalize-package-json.ts`.
+ */ 

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@comity-dev/package-tools",
+  "version": "0.1.0",
+  "description": "Comity package metadata tooling (export normalization, package.json normalization). Development tooling.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "comity": {
+    "layer": "dev-tooling"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "comity-normalize-exports": "./dist/bin/comity-normalize-exports.js",
+    "comity-normalize-package-json": "./dist/bin/comity-normalize-package-json.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "./dist"
+  ],
+  "dependencies": {
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}