@repokit/core 0.0.1

package/README.md

@@ -0,0 +1,204 @@
+<img src="media/repokit.webp" alt="Alt text" width="150px" />
+
+# repokit
+
+A knowledgebase for your repository - wrapped in a CLI.
+
+Repokit is designed for large teams in complex codebases to publish self-documenting commands, API's, and workflows to a central CLI.
+
+The Repokit CLI exists as a living source of documentation and knowledge - growing alongside your team.
+
+## Getting Started
+
+### Installation
+
+If you do not have node.js setup in your repository, you'll first want to install node.js.
+
+[NVM is a populat posix compliant installer](https://github.com/nvm-sh/nvm)
+
+Once installed, you can run the following in the root of your repository
+
+```bash
+npm init
+```
+
+If you don't have `typescript` already setup in your repository, you can run:
+
+```bash
+npm i -D typescript && tsc --init
+```
+
+Next, install repokit:
+
+```bash
+npm i -D @repokit/core
+# or
+yarn add -D @repokit/core
+# or
+pnpm add -D @repokit/core
+```
+
+Repokit will automatically create a config file named `repokit.ts` for you upon installing. Fill out this file with your desired settings.
+
+Here's an example of what Repokit's internal config looks like:
+
+```typescript
+import { RepoKitConfig } from "@repokit/core";
+
+export const RepoKit = new RepoKitConfig({
+  project: "Repokit",
+  commands: {
+    "build:rust": {
+      command: "cargo build --release",
+      description: "Build CLI in production mode",
+    },
+    "install:rust": {
+      command: "cargo install --path .",
+      description: "Installs the production CLI and adds it to your path",
+    },
+    "lint:ts": {
+      command:
+        "yarn oxlint --type-aware --type-check --report-unused-disable-directives --fix && yarn oxfmt",
+      description: "Lints typescript files using oxc",
+    },
+    "build:ts": {
+      command: "yarn ts-packager -e src",
+      description: "Builds the typescript package",
+    },
+  },
+});
+```
+
+To verify your configuration, run
+
+```bash
+repokit
+```
+
+The CLI will list out its internal commands as well as any commands you registered in your config file.
+
+Next run:
+
+```bash
+repokit onboard
+```
+
+### Building Your CLI
+
+To begin building your CLI, run:
+
+```bash
+repokit register ./path/to/your/feature
+```
+
+This command generates a tool definition for your feature that you can fill out using your tool's API's. When complete, save the file and run:
+
+```bash
+repokit <your-tool-name>
+```
+
+The CLI will list out your new tool's API's. To invoke any of them, run:
+
+```bash
+repokit <your-tool-name> <your-command-name>
+```
+
+### Reasoning about your toolchain
+
+As your toolchain grows it's possible to find yourself with hundreds, if not thousands of registered commands.
+
+To make reasoning about your commands easier, there are a few internal commands worth getting to know
+
+#### `repokit search`
+
+`repokit search` is a blanket search over all command definitions. Using it you can search for commands by name, owner, definition, location, or even the tools that it invokes.
+
+For example, let's say you wanted to list all commands that invoke `cargo`, you could run
+
+```bash
+repokit search cargo
+```
+
+If you wanted to search for all commands owned by an individual or team you could run
+
+```bash
+repokit search <person or team name>
+```
+
+If you wanted to search for commands under a given path you could run
+
+```bash
+repokit search path/within/your/codebase
+```
+
+You can query for just about anything you can imagine
+
+#### `repokit locate`
+
+Code changes can sometimes require updating command definitions. Repokit can easily locate any command's definition by name:
+
+```bash
+repokit locate <your-tool-name>
+```
+
+#### `repokit owners`
+
+If your team makes use of the `owners` attribute when defining your commands, you can easily list all commands owned by an individual or team
+
+```bash
+repokit list <owner>
+```
+
+`repokit list` can also accept `internal | registered | root` as an argument.
+
+`internal` will cause repokit to list out all of its internal commands
+
+`registered` will cause repokit to list out all of the commands your team has defined around your codebase
+
+`root` will cause repokit to list out all commands in your `repokit.ts` config
+
+### Best Practices for Registering Commands
+
+First and most simply - use verbose descriptions. Document flags, positionals, and environment variables required to invoke your tool.
+
+If your tool requires arguments, abstract common combinations of arguments into their own sub-commands. For example, instead of a single `build` command requiring flags to configure it, create sub commands that abstract commonly used combinations of parameters:
+
+```typescript
+import { RepoKitCommand } from "@repokit/core";
+
+export const Commands = new RepoKitCommand({
+  // ... command definition
+  commands: {
+    "build:local": {
+      command: "bazel build --env development",
+      description: "Builds in development mode",
+    },
+    "build:production": {
+      command: "bazel build --progress --stats --env production",
+      description: "Builds in production mode",
+    },
+  },
+});
+```
+
+When possible, prefer flags and positionals over environment variables. Often times your argv parsers will provide some out-of-the-box validations for free that environment variables simply don't get.
+
+#### Working Directories
+
+The commands you register onto the repokit toolchain will always be invoked using the working directory of the command's definition.
+
+If your command needs to reason about the file system, keep this in mind.
+
+## Motivation
+
+I worked in a codebase at Google that used just about every programming language in existence. Each team had their own methodology for exposing commands, scripts, and API's for their team's day-to-day development needs.
+
+Some teams used shell scripts, some used a tool called `bazel`, and some relied on good old `python ./path/to/my-script.py` or something similar.
+
+For engineers new and old to onboard to new features, they were often left stuck combing through these undocumented scripts and tools - tracking down environment variables, positionals, and flags to get necessary commands to succeed.
+
+Most of the time landing them in GChat asking for help.
+
+During my time there, I never met an engineer with a fully functioning local environment.
+
+It was there that I designed an early version **repokit.**

package/dist/cjs/CommandParser.js

@@ -0,0 +1,68 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandParser = void 0;
+const node_util_1 = require("node:util");
+const node_path_1 = require("node:path");
+const promises_1 = require("node:fs/promises");
+const node_fs_1 = require("node:fs");
+const TaskPooler_1 = require("./TaskPooler");
+const RepoKitCommand_1 = require("./RepoKitCommand");
+class CommandParser {
+    static parse() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { paths, root } = this.parsePaths();
+            if (!root || !(0, node_fs_1.existsSync)(root) || !(yield (0, promises_1.stat)(root)).isDirectory()) {
+                return console.log(JSON.stringify([]));
+            }
+            const pathList = paths.split(",").filter(Boolean);
+            const pool = new TaskPooler_1.TaskPooler();
+            const results = yield Promise.all(pathList.map(path => pool.enqueue(() => this.parseCommand((0, node_path_1.join)(root, path)))));
+            console.log(JSON.stringify(results.flat()));
+        });
+    }
+    static parseCommand(path) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const commands = [];
+            const declaredExports = yield Promise.resolve(`${path}`).then(s => require(s));
+            for (const key in declaredExports) {
+                if (declaredExports[key] instanceof RepoKitCommand_1.RepoKitCommand) {
+                    commands.push(Object.assign(Object.assign({}, declaredExports[key].toJSON()), { location: path }));
+                }
+            }
+            return commands;
+        });
+    }
+    static parsePaths() {
+        try {
+            return (0, node_util_1.parseArgs)({
+                options: {
+                    paths: {
+                        default: "",
+                        multiple: false,
+                        short: "p",
+                        type: "string",
+                    },
+                    root: {
+                        default: "",
+                        multiple: false,
+                        short: "r",
+                        type: "string",
+                    },
+                },
+            }).values;
+        }
+        catch (_a) {
+            return { paths: "", root: "" };
+        }
+    }
+}
+exports.CommandParser = CommandParser;

package/dist/cjs/ConfigurationParser.js

@@ -0,0 +1,46 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigurationParser = void 0;
+const node_util_1 = require("node:util");
+const node_path_1 = require("node:path");
+const node_fs_1 = require("node:fs");
+const RepoKitConfig_1 = require("./RepoKitConfig");
+class ConfigurationParser {
+    static parse() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const root = this.parseRoot();
+            const path = (0, node_path_1.join)(root, "repokit.ts");
+            if (!(0, node_fs_1.existsSync)(path)) {
+                return;
+            }
+            const config = yield Promise.resolve(`${path}`).then(s => require(s));
+            for (const key in config) {
+                if (config[key] instanceof RepoKitConfig_1.RepoKitConfig) {
+                    return console.log(JSON.stringify(config[key]));
+                }
+            }
+        });
+    }
+    static parseRoot() {
+        return (0, node_util_1.parseArgs)({
+            options: {
+                root: {
+                    default: "",
+                    multiple: false,
+                    short: "r",
+                    type: "string",
+                },
+            },
+        }).values.root;
+    }
+}
+exports.ConfigurationParser = ConfigurationParser;

package/dist/cjs/RepoKitCommand.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RepoKitCommand = void 0;
+class RepoKitCommand {
+    constructor({ name, description, owner = "", commands = {}, }) {
+        this.name = name;
+        this.owner = owner;
+        this.commands = commands;
+        this.description = description;
+    }
+    toJSON() {
+        const { name, owner, commands, description } = this;
+        return { name, owner, commands, description };
+    }
+}
+exports.RepoKitCommand = RepoKitCommand;

package/dist/cjs/RepoKitConfig.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RepoKitConfig = void 0;
+class RepoKitConfig {
+    constructor({ project, commands = {} }) {
+        this.project = project;
+        this.commands = commands;
+    }
+}
+exports.RepoKitConfig = RepoKitConfig;

package/dist/cjs/TaskPooler.js

@@ -0,0 +1,42 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskPooler = void 0;
+const event_emitter_1 = require("@figliolia/event-emitter");
+class TaskPooler {
+    constructor(maxSize = 10) {
+        this.maxSize = maxSize;
+        this.IDs = new event_emitter_1.AutoIncrementingID();
+        this.runningTasks = new Map();
+    }
+    enqueue(task) {
+        return new Promise(resolve => {
+            if (this.runningTasks.size < 10) {
+                return resolve(this.indexRunningTask(task));
+            }
+            resolve(this.indexBehindNextOpening(task));
+        });
+    }
+    indexRunningTask(task) {
+        const ID = this.IDs.get();
+        const promise = task();
+        this.runningTasks.set(ID, promise);
+        void promise.finally(() => this.runningTasks.delete(ID));
+        return promise;
+    }
+    indexBehindNextOpening(task) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield Promise.race(this.runningTasks.values());
+            return this.indexRunningTask(task);
+        });
+    }
+}
+exports.TaskPooler = TaskPooler;

package/dist/cjs/commands/parse_commands.js

@@ -0,0 +1,15 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const CommandParser_1 = require("../CommandParser");
+void (() => __awaiter(void 0, void 0, void 0, function* () {
+    yield CommandParser_1.CommandParser.parse();
+}))();

package/dist/cjs/commands/parse_configuration.js

@@ -0,0 +1,15 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const ConfigurationParser_1 = require("../ConfigurationParser");
+void (() => __awaiter(void 0, void 0, void 0, function* () {
+    yield ConfigurationParser_1.ConfigurationParser.parse();
+}))();

package/dist/cjs/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./RepoKitConfig"), exports);
+__exportStar(require("./RepoKitCommand"), exports);
+__exportStar(require("./types"), exports);

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/mjs/CommandParser.js

@@ -0,0 +1,51 @@
+import { parseArgs } from "node:util";
+import { join } from "node:path";
+import { stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { TaskPooler } from "./TaskPooler.js";
+import { RepoKitCommand } from "./RepoKitCommand.js";
+export class CommandParser {
+    static async parse() {
+        const { paths, root } = this.parsePaths();
+        if (!root || !existsSync(root) || !(await stat(root)).isDirectory()) {
+            return console.log(JSON.stringify([]));
+        }
+        const pathList = paths.split(",").filter(Boolean);
+        const pool = new TaskPooler();
+        const results = await Promise.all(pathList.map(path => pool.enqueue(() => this.parseCommand(join(root, path)))));
+        console.log(JSON.stringify(results.flat()));
+    }
+    static async parseCommand(path) {
+        const commands = [];
+        const declaredExports = await import(path);
+        for (const key in declaredExports) {
+            if (declaredExports[key] instanceof RepoKitCommand) {
+                commands.push({ ...declaredExports[key].toJSON(), location: path });
+            }
+        }
+        return commands;
+    }
+    static parsePaths() {
+        try {
+            return parseArgs({
+                options: {
+                    paths: {
+                        default: "",
+                        multiple: false,
+                        short: "p",
+                        type: "string",
+                    },
+                    root: {
+                        default: "",
+                        multiple: false,
+                        short: "r",
+                        type: "string",
+                    },
+                },
+            }).values;
+        }
+        catch {
+            return { paths: "", root: "" };
+        }
+    }
+}

package/dist/mjs/ConfigurationParser.js

@@ -0,0 +1,31 @@
+import { parseArgs } from "node:util";
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { RepoKitConfig } from "./RepoKitConfig.js";
+export class ConfigurationParser {
+    static async parse() {
+        const root = this.parseRoot();
+        const path = join(root, "repokit.ts");
+        if (!existsSync(path)) {
+            return;
+        }
+        const config = await import(path);
+        for (const key in config) {
+            if (config[key] instanceof RepoKitConfig) {
+                return console.log(JSON.stringify(config[key]));
+            }
+        }
+    }
+    static parseRoot() {
+        return parseArgs({
+            options: {
+                root: {
+                    default: "",
+                    multiple: false,
+                    short: "r",
+                    type: "string",
+                },
+            },
+        }).values.root;
+    }
+}

package/dist/mjs/RepoKitCommand.js

@@ -0,0 +1,16 @@
+export class RepoKitCommand {
+    name;
+    owner;
+    description;
+    commands;
+    constructor({ name, description, owner = "", commands = {}, }) {
+        this.name = name;
+        this.owner = owner;
+        this.commands = commands;
+        this.description = description;
+    }
+    toJSON() {
+        const { name, owner, commands, description } = this;
+        return { name, owner, commands, description };
+    }
+}

package/dist/mjs/RepoKitConfig.js

@@ -0,0 +1,8 @@
+export class RepoKitConfig {
+    project;
+    commands;
+    constructor({ project, commands = {} }) {
+        this.project = project;
+        this.commands = commands;
+    }
+}

package/dist/mjs/TaskPooler.js

@@ -0,0 +1,28 @@
+import { AutoIncrementingID } from "@figliolia/event-emitter";
+export class TaskPooler {
+    maxSize;
+    IDs = new AutoIncrementingID();
+    runningTasks = new Map();
+    constructor(maxSize = 10) {
+        this.maxSize = maxSize;
+    }
+    enqueue(task) {
+        return new Promise(resolve => {
+            if (this.runningTasks.size < 10) {
+                return resolve(this.indexRunningTask(task));
+            }
+            resolve(this.indexBehindNextOpening(task));
+        });
+    }
+    indexRunningTask(task) {
+        const ID = this.IDs.get();
+        const promise = task();
+        this.runningTasks.set(ID, promise);
+        void promise.finally(() => this.runningTasks.delete(ID));
+        return promise;
+    }
+    async indexBehindNextOpening(task) {
+        await Promise.race(this.runningTasks.values());
+        return this.indexRunningTask(task);
+    }
+}

package/dist/mjs/commands/parse_commands.js

@@ -0,0 +1,4 @@
+import { CommandParser } from "../CommandParser.js";
+void (async () => {
+    await CommandParser.parse();
+})();

package/dist/mjs/commands/parse_configuration.js

@@ -0,0 +1,4 @@
+import { ConfigurationParser } from "../ConfigurationParser.js";
+void (async () => {
+    await ConfigurationParser.parse();
+})();

package/dist/mjs/index.js

@@ -0,0 +1,3 @@
+export * from "./RepoKitConfig.js";
+export * from "./RepoKitCommand.js";
+export * from "./types.js";

package/dist/mjs/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "exports": "./index.js"
+}

package/dist/mjs/types.js

@@ -0,0 +1 @@
+export {};

package/dist/types/CommandParser.d.ts

@@ -0,0 +1,5 @@
+export declare class CommandParser {
+    static parse(): Promise<void>;
+    private static parseCommand;
+    private static parsePaths;
+}

package/dist/types/ConfigurationParser.d.ts

@@ -0,0 +1,4 @@
+export declare class ConfigurationParser {
+    static parse(): Promise<void>;
+    private static parseRoot;
+}

package/dist/types/RepoKitCommand.d.ts

@@ -0,0 +1,14 @@
+import type { ICommand, IRepoKitCommand } from "./types";
+export declare class RepoKitCommand {
+    name: string;
+    owner: string;
+    description: string;
+    commands: Record<string, ICommand>;
+    constructor({ name, description, owner, commands, }: IRepoKitCommand);
+    toJSON(): {
+        name: string;
+        owner: string;
+        commands: Record<string, ICommand>;
+        description: string;
+    };
+}

package/dist/types/RepoKitConfig.d.ts

@@ -0,0 +1,6 @@
+import type { ICommand, IRepoKitConfig } from "./types";
+export declare class RepoKitConfig implements Required<IRepoKitConfig> {
+    project: string;
+    commands: Record<string, ICommand>;
+    constructor({ project, commands }: IRepoKitConfig);
+}

package/dist/types/TaskPooler.d.ts

@@ -0,0 +1,10 @@
+import type { AsyncTask } from "./types";
+export declare class TaskPooler<T> {
+    maxSize: number;
+    private readonly IDs;
+    private readonly runningTasks;
+    constructor(maxSize?: number);
+    enqueue(task: AsyncTask<T>): Promise<T>;
+    private indexRunningTask;
+    private indexBehindNextOpening;
+}

package/dist/types/commands/parse_commands.d.ts

@@ -0,0 +1 @@
+export {};