depflow 3.0.0-dev.10 → 3.0.0-dev.12

package/dist/config/TSConfig.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Updates and persists TypeScript path mappings from compiled path aliases.
+ * @license Apache-2.0
+ */
+import { Logger } from '@netfeez/vterm';
+import schema from '../schema/schema.js';
+import Settings from './Settings.js';
+import type AliasCompiler from '../resolve/AliasCompiler.js';
+export declare class TSConfig extends Settings<typeof schema.TSConfig> {
+    protected static schema: import("@netfeez/schema").Schema<{
+        readonly type: "object";
+        readonly additional: true;
+        readonly keys: {
+            readonly compilerOptions: {
+                readonly type: "object";
+                readonly additional: true;
+                readonly keys: {
+                    readonly rootDir: {
+                        readonly type: "string";
+                        readonly description: "Root directory of the TypeScript source files.";
+                    };
+                    readonly outDir: {
+                        readonly type: "string";
+                        readonly description: "Output directory for the compiled files.";
+                    };
+                    readonly paths: {
+                        readonly type: "object";
+                        readonly additional: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                            };
+                        };
+                        readonly description: "Path mapping aliases used by TypeScript to resolve modules.";
+                    };
+                };
+                readonly description: "The compiler options object of the tsconfig file.";
+            };
+        };
+        readonly description: "Structure of a tsconfig.json file.";
+    }>;
+    protected logger: Logger;
+    constructor(data: TSConfig.Data, options?: TSConfig.Options);
+    /**
+     * The formats of the tsconfig file: JSON only, so it never reaches a YAML parser.
+     * @returns The JSON codec of the file.
+     */
+    protected static get codecs(): readonly Settings.AnyCodec[];
+    /**
+     * Updates the paths in the tsconfig data based on the provided compiled aliases.
+     * It ensures that the compilerOptions and paths properties exist in the tsconfig data, and then iterates through the compiled aliases to construct the appropriate path mappings.
+     * For each alias, it calculates the relative path from the project root to the local target and normalizes it. If the alias is a wildcard, it appends '/*' to the target path.
+     * Finally, it updates the paths in the tsconfig data with the new mappings, allowing TypeScript to resolve module paths according to the defined aliases.
+     * @param aliases - An array of compiled aliases containing alias names, target paths, and wildcard information.
+     */
+    updatePaths(aliases: AliasCompiler.CompiledAlias[]): void;
+    /**
+     * Saves the current tsconfig data to a file.
+     * It constructs the path to the tsconfig file using the project root and filename, converts the data to a JSON string with proper formatting, and writes it to the file system using the File.write method.
+     * The method also includes error handling to log any issues that occur during the save process, ensuring that users are informed of any problems when attempting to save the tsconfig configuration.
+     * @param path - The path to the tsconfig file where the data should be saved.
+     * @returns A promise that resolves when the save operation is complete, or rejects if an error occurs during the process.
+     */
+    save(path?: string): Promise<void>;
+}
+export declare namespace TSConfig {
+    type Data = schema.TSConfig.Root;
+    interface Options extends Settings.Options {
+        logger?: Logger;
+    }
+}
+export default TSConfig;

package/dist/config/TSConfig.js

@@ -0,0 +1,73 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Updates and persists TypeScript path mappings from compiled path aliases.
+ * @license Apache-2.0
+ */
+import { Logger } from '@netfeez/vterm';
+import { Path } from '@netfeez/common-node';
+import schema from '../schema/schema.js';
+import Settings from './Settings.js';
+import JsonCodec from './codecs/JsonCodec.js';
+export class TSConfig extends Settings {
+    static schema = schema.TSConfig;
+    logger;
+    constructor(data, options = {}) {
+        super(data, options);
+        this.logger = options.logger || new Logger({ name: 'TS-CFG' });
+    }
+    /**
+     * The formats of the tsconfig file: JSON only, so it never reaches a YAML parser.
+     * @returns The JSON codec of the file.
+     */
+    static get codecs() { return [new JsonCodec()]; }
+    /**
+     * Updates the paths in the tsconfig data based on the provided compiled aliases.
+     * It ensures that the compilerOptions and paths properties exist in the tsconfig data, and then iterates through the compiled aliases to construct the appropriate path mappings.
+     * For each alias, it calculates the relative path from the project root to the local target and normalizes it. If the alias is a wildcard, it appends '/*' to the target path.
+     * Finally, it updates the paths in the tsconfig data with the new mappings, allowing TypeScript to resolve module paths according to the defined aliases.
+     * @param aliases - An array of compiled aliases containing alias names, target paths, and wildcard information.
+     */
+    updatePaths(aliases) {
+        if (!this.data.compilerOptions)
+            this.data.compilerOptions = {};
+        if (!this.data.compilerOptions.paths)
+            this.data.compilerOptions.paths = {};
+        const projectRoot = Path.dirname(this.path);
+        for (const alias of aliases) {
+            const key = alias.isWildcard ? `${alias.alias}/*` : alias.alias;
+            let target = Path.diff(projectRoot, alias.targets.local);
+            target = target.startsWith('.') ? target : `./${target}`;
+            target = Path.normalize(target);
+            let typeTarget;
+            if (alias.targets.type) {
+                typeTarget = Path.diff(projectRoot, alias.targets.type);
+                typeTarget = typeTarget.startsWith('.') ? typeTarget : `./${typeTarget}`;
+                typeTarget = Path.normalize(typeTarget);
+            }
+            if (alias.isWildcard) {
+                const suffix = target.endsWith('/') ? '*' : '/*';
+                target = `${target}${suffix}`;
+                if (typeTarget) {
+                    typeTarget = `${typeTarget}${suffix}`;
+                }
+            }
+            this.data.compilerOptions.paths[key] = typeTarget ? [typeTarget, target] : [target];
+        }
+    }
+    /**
+     * Saves the current tsconfig data to a file.
+     * It constructs the path to the tsconfig file using the project root and filename, converts the data to a JSON string with proper formatting, and writes it to the file system using the File.write method.
+     * The method also includes error handling to log any issues that occur during the save process, ensuring that users are informed of any problems when attempting to save the tsconfig configuration.
+     * @param path - The path to the tsconfig file where the data should be saved.
+     * @returns A promise that resolves when the save operation is complete, or rejects if an error occurs during the process.
+     */
+    async save(path = this.path) {
+        await super.save(path);
+        if (path !== this.path)
+            this.path = path;
+        const filename = Path.fileName(path);
+        this.logger.log(`&C2Saved file &C4${filename}&C2 successfully.`);
+    }
+}
+export default TSConfig;
+//# sourceMappingURL=TSConfig.js.map

package/dist/config/TSConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TSConfig.js","sourceRoot":"","sources":["../../src/config/TSConfig.ts"],"names":[],"mappings":"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"}

package/dist/config/codecs/JsonCodec.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Reads and writes a config file as plain JSON.
+ * @license Apache-2.0
+ */
+import type { JsonValue } from '@netfeez/yaml';
+import type Settings from '../Settings.js';
+/**
+ * Reads and writes a config file as plain JSON.
+ *
+ * JSON preserves nothing around the values, so it has no document of its own: the data is the
+ * document, and every save regenerates the file from it.
+ */
+export declare class JsonCodec implements Settings.Codec<null, JsonValue> {
+    /** The file extensions this codec is selected by. */
+    readonly extensions: readonly string[];
+    /**
+     * Parses the JSON text into the data it holds.
+     * @param text - The JSON text of the file.
+     * @returns The data and the document of the file, or `null` when the text holds no document.
+     * @throws { SyntaxError } When the text is not valid JSON.
+     */
+    decode(text: string): Settings.Decoded<null> | null;
+    /** JSON has no document to create: the data is the document. **/
+    create(): null;
+    /** Renders the data as indented JSON. **/
+    encode(data: JsonValue, document: null): string;
+}
+export declare namespace JsonCodec { }
+export default JsonCodec;

package/dist/config/codecs/JsonCodec.js

@@ -0,0 +1,31 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Reads and writes a config file as plain JSON.
+ * @license Apache-2.0
+ */
+/**
+ * Reads and writes a config file as plain JSON.
+ *
+ * JSON preserves nothing around the values, so it has no document of its own: the data is the
+ * document, and every save regenerates the file from it.
+ */
+export class JsonCodec {
+    /** The file extensions this codec is selected by. */
+    extensions = ['.json'];
+    /**
+     * Parses the JSON text into the data it holds.
+     * @param text - The JSON text of the file.
+     * @returns The data and the document of the file, or `null` when the text holds no document.
+     * @throws { SyntaxError } When the text is not valid JSON.
+     */
+    decode(text) {
+        const data = JSON.parse(text);
+        return data === null ? null : { data, document: null };
+    }
+    /** JSON has no document to create: the data is the document. **/
+    create() { return null; }
+    /** Renders the data as indented JSON. **/
+    encode(data, document) { return JSON.stringify(data, null, 4); }
+}
+export default JsonCodec;
+//# sourceMappingURL=JsonCodec.js.map

package/dist/config/codecs/JsonCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonCodec.js","sourceRoot":"","sources":["../../../src/config/codecs/JsonCodec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;;GAKG;AACH,MAAM,OAAO,SAAS;IAClB,qDAAqD;IACrC,UAAU,GAAsB,CAAE,OAAO,CAAE,CAAC;IAE5D;;;;;OAKG;IACI,MAAM,CAAC,IAAY;QACtB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9B,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC3D,CAAC;IAED,iEAAiE;IAC1D,MAAM,KAAW,OAAO,IAAI,CAAC,CAAC,CAAC;IAEtC,0CAA0C;IACnC,MAAM,CAAC,IAAe,EAAE,QAAc,IAAY,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;CACnG;AAID,eAAe,SAAS,CAAC"}

package/dist/config/codecs/YamlCodec.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Reads and writes a config file as YAML, preserving the formatting of the file it was read from.
+ * @license Apache-2.0
+ */
+import Schema, { Definition } from '@netfeez/schema';
+import { type Document, type JsonValue } from '@netfeez/yaml';
+import type Settings from '../Settings.js';
+/**
+ * Reads and writes a config file as YAML, preserving the formatting of the file it was read from.
+ *
+ * The document is the YAML tree: the values it holds, plus everything YAML keeps around them (key
+ * order, indentation, comments). A document created from scratch is decorated with the file header
+ * and with the description the schema declares for each key, so a generated config documents itself.
+ */
+export declare class YamlCodec implements Settings.Codec<Document, JsonValue> {
+    /** The file extensions this codec is selected by. */
+    readonly extensions: readonly string[];
+    protected schema: Schema<Definition.Definition>;
+    protected header: string[];
+    /**
+     * Creates the codec.
+     * @param schema - The schema whose key descriptions document a generated file.
+     * @param options - Options for the codec.
+     */
+    constructor(schema: Schema<Definition.Definition>, options?: YamlCodec.Options);
+    /**
+     * Parses the YAML text into the document it describes.
+     * @param text - The YAML text of the file.
+     * @returns The data and the document of the file, or `null` when the text holds no document.
+     * @throws { YamlError } When the text is not valid YAML.
+     *
+     * @remarks A file holding only comments, or nothing at all, parses into an empty tree: it has
+     * no data, so there is nothing to load and the defaults of the schema take over.
+     */
+    decode(text: string): Settings.Decoded<Document> | null;
+    /**
+     * Creates a document holding the data, with the file header and the schema descriptions.
+     * @param data - The data to hold in the new document.
+     * @returns The new document.
+     */
+    create(data: JsonValue): Document;
+    /**
+     * Synchronizes the data into the document and renders it, leaving everything the data does not
+     * touch (key order, indentation, and the comments of the keys it leaves alone) as it was.
+     * @param data - The data to render.
+     * @param document - The document the data is rendered through.
+     * @returns The YAML text of the document.
+     */
+    encode(data: JsonValue, document: Document): string;
+    /** Writes the file header and the schema description of every key the document has. **/
+    private decorate;
+    /** The description of every declared top-level key, as the comment lines of a generated file. **/
+    private descriptions;
+}
+export declare namespace YamlCodec {
+    interface Options {
+        /** The raw lines written at the top of a generated file, pushed verbatim. */
+        header?: string[];
+    }
+}
+export default YamlCodec;

package/dist/config/codecs/YamlCodec.js

@@ -0,0 +1,89 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Reads and writes a config file as YAML, preserving the formatting of the file it was read from.
+ * @license Apache-2.0
+ */
+import Yaml from '@netfeez/yaml';
+/**
+ * Reads and writes a config file as YAML, preserving the formatting of the file it was read from.
+ *
+ * The document is the YAML tree: the values it holds, plus everything YAML keeps around them (key
+ * order, indentation, comments). A document created from scratch is decorated with the file header
+ * and with the description the schema declares for each key, so a generated config documents itself.
+ */
+export class YamlCodec {
+    /** The file extensions this codec is selected by. */
+    extensions = ['.yaml', '.yml'];
+    schema;
+    header;
+    /**
+     * Creates the codec.
+     * @param schema - The schema whose key descriptions document a generated file.
+     * @param options - Options for the codec.
+     */
+    constructor(schema, options = {}) {
+        this.schema = schema;
+        this.header = options.header ?? [];
+    }
+    /**
+     * Parses the YAML text into the document it describes.
+     * @param text - The YAML text of the file.
+     * @returns The data and the document of the file, or `null` when the text holds no document.
+     * @throws { YamlError } When the text is not valid YAML.
+     *
+     * @remarks A file holding only comments, or nothing at all, parses into an empty tree: it has
+     * no data, so there is nothing to load and the defaults of the schema take over.
+     */
+    decode(text) {
+        const document = Yaml.parse(text);
+        const data = document.toJS();
+        return data === null ? null : { data, document };
+    }
+    /**
+     * Creates a document holding the data, with the file header and the schema descriptions.
+     * @param data - The data to hold in the new document.
+     * @returns The new document.
+     */
+    create(data) {
+        const document = Yaml.create(data);
+        this.decorate(document);
+        return document;
+    }
+    /**
+     * Synchronizes the data into the document and renders it, leaving everything the data does not
+     * touch (key order, indentation, and the comments of the keys it leaves alone) as it was.
+     * @param data - The data to render.
+     * @param document - The document the data is rendered through.
+     * @returns The YAML text of the document.
+     */
+    encode(data, document) {
+        document.sync(data);
+        return document.dump();
+    }
+    /** Writes the file header and the schema description of every key the document has. **/
+    decorate(document) {
+        if (this.header.length)
+            document.header.push(...this.header);
+        for (const [key, description] of Object.entries(this.descriptions())) {
+            const node = document.get(key);
+            if (!node)
+                continue;
+            node.meta.lead = description.map(line => line.startsWith('#') ? line : `# ${line}`);
+        }
+    }
+    /** The description of every declared top-level key, as the comment lines of a generated file. **/
+    descriptions() {
+        const definition = this.schema.definition;
+        if (definition.type !== 'object' || !definition.keys)
+            return {};
+        const descriptions = {};
+        for (const [key, value] of Object.entries(definition.keys)) {
+            if (!value.description)
+                continue;
+            descriptions[key] = value.description.split('\n').map(line => line.trim());
+        }
+        return descriptions;
+    }
+}
+export default YamlCodec;
+//# sourceMappingURL=YamlCodec.js.map

package/dist/config/codecs/YamlCodec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"YamlCodec.js","sourceRoot":"","sources":["../../../src/config/codecs/YamlCodec.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,IAAuC,MAAM,eAAe,CAAC;AAKpE;;;;;;GAMG;AACH,MAAM,OAAO,SAAS;IAClB,qDAAqD;IACrC,UAAU,GAAsB,CAAE,OAAO,EAAE,MAAM,CAAE,CAAC;IAE1D,MAAM,CAAgC;IACtC,MAAM,CAAW;IAE3B;;;;OAIG;IACH,YAAmB,MAAqC,EAAE,OAAO,GAAsB,EAAE;QACrF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;IACvC,CAAC;IAED;;;;;;;;OAQG;IACI,MAAM,CAAC,IAAY;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC7B,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACrD,CAAC;IAED;;;;OAIG;IACI,MAAM,CAAC,IAAe;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACxB,OAAO,QAAQ,CAAC;IACpB,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAC,IAAe,EAAE,QAAkB;QAC7C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,wFAAwF;IAChF,QAAQ,CAAC,QAAkB;QAC/B,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC7D,KAAK,MAAM,CAAC,GAAG,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,IAAI;gBAAE,SAAS;YACpB,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QACxF,CAAC;IACL,CAAC;IAED,kGAAkG;IAC1F,YAAY;QAChB,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;QAC1C,IAAI,UAAU,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,IAAI;YAAE,OAAO,EAAE,CAAC;QAChE,MAAM,YAAY,GAA6B,EAAE,CAAC;QAClD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACzD,IAAI,CAAC,KAAK,CAAC,WAAW;gBAAE,SAAS;YACjC,YAAY,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,YAAY,CAAC;IACxB,CAAC;CACJ;AASD,eAAe,SAAS,CAAC"}

package/dist/dependency/DepUtils.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Dependency source utilities: git repository validation and identity derivation.
+ * @license Apache-2.0
+ */
+export declare namespace DepUtils {
+    /**
+     * A repository in the canonical form `git clone` accepts: a remote over one of the transports it
+     * speaks, or a local path of a repository, always ending in `.git`. The name of a dependency is
+     * never derived from it, only the repo itself is.
+     *
+     * @remarks Every transport is spelled out so the accepted shapes are readable, but the `.git`
+     * suffix is what all of them share and what {@link DepUtils.repo} enforces, so the last member is
+     * the one that decides.
+     */
+    type Repo = `https://${string}.git` | `http://${string}.git` | `ssh://${string}.git` | `git://${string}.git` | `file://${string}.git` | `git@${string}.git` | `${string}.git`;
+    /**
+     * What a repository reference resolves to: the URL `git clone` is given and the name GitHub
+     * derives from it.
+     */
+    interface Reference {
+        /** The repository, canonical: a value {@link DepUtils.Repo} accepts whatever form it came in. */
+        repo: Repo;
+        /** The `<user>/<name>` GitHub derives, or `null` when the reference is not a GitHub one. **/
+        name: string | null;
+    }
+    /**
+     * Parses a repository reference into the repository git clones from and the name GitHub derives.
+     *
+     * A GitHub repository may be written as the bare `user/repo` shorthand, as an HTTP(S) URL or as an
+     * SCP like ssh address, with or without the `.git` suffix; every one of them is canonicalized to
+     * the same repository. Any other repository is accepted as it stands when it is a value
+     * {@link DepUtils.Repo} accepts, and carries no derivable name.
+     * @param reference - The repository reference as a user writes it.
+     * @returns The canonical repository and the derived name, `null` when there is none.
+     * @throws { Error } When the reference is not a clonable repository.
+     *
+     * @example
+     * ```ts
+     * DepUtils.parse('netfeez/omega');
+     * // { repo: 'https://github.com/netfeez/omega.git', name: 'netfeez/omega' }
+     * ```
+     */
+    function parse(reference: string): Reference;
+    /**
+     * Validates that the provided value is a repository `git clone` accepts, and says what it is not when
+     * it does not: a URL with its scheme, an SCP like address or a local path of a repository.
+     * @param repo - The repository value to validate.
+     * @throws Will throw an error if the value is not a clonable repository.
+     *
+     * @remarks A repository always carries the `.git` suffix, whichever transport it comes in: it is what
+     * tells a repository apart from a page, a package or a folder, and the name of the dependency is
+     * derived from the same suffix, so both read one repository.
+     *
+     * @example
+     * ```ts
+     * DepUtils.repo('https://github.com/NetFeez/omega.git');
+     * ```
+     */
+    function repo(repo: unknown): asserts repo is Repo;
+    /**
+     * Extracts the name a dependency is known by from its repository reference.
+     *
+     * Only a GitHub repository has a name that can be derived without asking, and the name it derives
+     * is the one the alias of the dependency takes everywhere else, so it is derived here and nowhere
+     * else.
+     * @param repo - The repository reference, in any of the forms {@link DepUtils.parse} accepts.
+     * @returns The repository name, as `<user>/<name>`.
+     * @throws { Error } When the repository is not a GitHub one, saying the name has to be given.
+     *
+     * @example
+     * ```ts
+     * DepUtils.getRepoName('https://github.com/NetFeez/omega.git'); // 'NetFeez/omega'
+     * ```
+     */
+    function getRepoName(repo: string): string;
+}
+export default DepUtils;

package/dist/dependency/DepUtils.js

@@ -0,0 +1,122 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Dependency source utilities: git repository validation and identity derivation.
+ * @license Apache-2.0
+ */
+export var DepUtils;
+(function (DepUtils) {
+    /**
+     * Matches what `git clone` accepts, in the transports it speaks: a URL with its scheme, an SCP
+     * like address, or a local path of a repository.
+     */
+    const CLONEABLE_REGEX = /^(?:(?:https?|ssh|git|file):\/\/|git@)\S+$|\S*\.git$/;
+    /**
+     * Matches a GitHub repository over HTTP, with or without the `.git` suffix, and captures its user
+     * and name.
+     */
+    const GITHUB_HTTP_REGEX = /^(https?):\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/;
+    /**
+     * Matches a GitHub repository over SSH in the SCP like form, with or without the `.git` suffix and
+     * tolerating the stray slash some clients write after the colon (`git@github.com:/user/repo`).
+     */
+    const GITHUB_SSH_REGEX = /^git@github\.com:?\/?([^/]+)\/([^/]+?)(?:\.git)?$/;
+    /**
+     * Matches the bare `user/repo` shorthand GitHub itself accepts, without a scheme and with or
+     * without the `.git` suffix.
+     */
+    const GITHUB_SHORT_REGEX = /^([A-Za-z0-9][A-Za-z0-9._-]*)\/([A-Za-z0-9][A-Za-z0-9._-]*?)(?:\.git)?$/;
+    /**
+     * The suffix that tells a repository from anything else, checked on the value as a whole instead of
+     * anchoring it, so a local path of a repository keeps validating wherever it lives.
+     */
+    const GIT_SUFFIX_REGEX = /\.git$/;
+    /**
+     * The failure every rejected reference is reported with, so a caller sees what was expected of it.
+     * @param reference - The value that was refused.
+     * @returns The error describing what a repository reference may be.
+     **/
+    function notClonable(reference) {
+        return new Error(`Not a clonable git repository: "${reference}". Pass a user/repo pair, a repository ending in .git, a URL git can clone, an ssh address or a local path of a repository.`);
+    }
+    /**
+     * Parses a repository reference into the repository git clones from and the name GitHub derives.
+     *
+     * A GitHub repository may be written as the bare `user/repo` shorthand, as an HTTP(S) URL or as an
+     * SCP like ssh address, with or without the `.git` suffix; every one of them is canonicalized to
+     * the same repository. Any other repository is accepted as it stands when it is a value
+     * {@link DepUtils.Repo} accepts, and carries no derivable name.
+     * @param reference - The repository reference as a user writes it.
+     * @returns The canonical repository and the derived name, `null` when there is none.
+     * @throws { Error } When the reference is not a clonable repository.
+     *
+     * @example
+     * ```ts
+     * DepUtils.parse('netfeez/omega');
+     * // { repo: 'https://github.com/netfeez/omega.git', name: 'netfeez/omega' }
+     * ```
+     */
+    function parse(reference) {
+        if (typeof reference !== 'string' || !reference.trim())
+            throw notClonable(reference);
+        const value = reference.trim();
+        const http = value.match(GITHUB_HTTP_REGEX);
+        if (http)
+            return { repo: `${http[1]}://github.com/${http[2]}/${http[3]}.git`, name: `${http[2]}/${http[3]}` };
+        const ssh = value.match(GITHUB_SSH_REGEX);
+        if (ssh)
+            return { repo: `git@github.com:${ssh[1]}/${ssh[2]}.git`, name: `${ssh[1]}/${ssh[2]}` };
+        const short = value.match(GITHUB_SHORT_REGEX);
+        if (short)
+            return { repo: `https://github.com/${short[1]}/${short[2]}.git`, name: `${short[1]}/${short[2]}` };
+        if (!CLONEABLE_REGEX.test(value) || !GIT_SUFFIX_REGEX.test(value))
+            throw notClonable(value);
+        return { repo: value, name: null };
+    }
+    DepUtils.parse = parse;
+    /**
+     * Validates that the provided value is a repository `git clone` accepts, and says what it is not when
+     * it does not: a URL with its scheme, an SCP like address or a local path of a repository.
+     * @param repo - The repository value to validate.
+     * @throws Will throw an error if the value is not a clonable repository.
+     *
+     * @remarks A repository always carries the `.git` suffix, whichever transport it comes in: it is what
+     * tells a repository apart from a page, a package or a folder, and the name of the dependency is
+     * derived from the same suffix, so both read one repository.
+     *
+     * @example
+     * ```ts
+     * DepUtils.repo('https://github.com/NetFeez/omega.git');
+     * ```
+     */
+    function repo(repo) {
+        if (typeof repo !== 'string' || !repo.trim())
+            throw new Error(`Not a clonable git repository: "${repo}".`);
+        if (!CLONEABLE_REGEX.test(repo) || !GIT_SUFFIX_REGEX.test(repo.trim()))
+            throw new Error(`Not a clonable git repository: "${repo}". Pass a repository ending in .git, a URL git can clone, an ssh address or a local path of a repository.`);
+    }
+    DepUtils.repo = repo;
+    /**
+     * Extracts the name a dependency is known by from its repository reference.
+     *
+     * Only a GitHub repository has a name that can be derived without asking, and the name it derives
+     * is the one the alias of the dependency takes everywhere else, so it is derived here and nowhere
+     * else.
+     * @param repo - The repository reference, in any of the forms {@link DepUtils.parse} accepts.
+     * @returns The repository name, as `<user>/<name>`.
+     * @throws { Error } When the repository is not a GitHub one, saying the name has to be given.
+     *
+     * @example
+     * ```ts
+     * DepUtils.getRepoName('https://github.com/NetFeez/omega.git'); // 'NetFeez/omega'
+     * ```
+     */
+    function getRepoName(repo) {
+        const { name } = parse(repo);
+        if (!name)
+            throw new Error(`Cannot derive a name from "${repo}": only GitHub repositories are named automatically, pass the name yourself.`);
+        return name;
+    }
+    DepUtils.getRepoName = getRepoName;
+})(DepUtils || (DepUtils = {}));
+export default DepUtils;
+//# sourceMappingURL=DepUtils.js.map

package/dist/dependency/DepUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DepUtils.js","sourceRoot":"","sources":["../../src/dependency/DepUtils.ts"],"names":[],"mappings":"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"}