depflow 3.0.0-dev.10 → 3.0.0-dev.11

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,50 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Dependency source utilities: git repository validation and identity derivation.
+ * @license Apache-2.0
+ */
+export declare namespace DepUtils {
+    /**
+     * Anything `git clone` accepts as a repository: a remote over one of the transports it speaks, or
+     * a local path of a repository. 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`;
+    /**
+     * 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 URL.
+     *
+     * 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 URL.
+     * @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,71 @@
+/**
+ * @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 URL and captures its user and name, tolerating a missing `.git` suffix.
+     */
+    const GITHUB_REPO_REGEX = /^(?:https:\/\/github\.com\/([^/]+)\/([^/.]+)(?:\.git)?|git@github\.com:([^/]+)\/([^/.]+)(?:\.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$/;
+    /**
+     * 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 URL.
+     *
+     * 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 URL.
+     * @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 match = repo.match(GITHUB_REPO_REGEX);
+        if (match) {
+            const user = match[1] || match[3];
+            const repoName = match[2] || match[4];
+            return `${user}.${repoName}`;
+        }
+        throw new Error(`Cannot derive a name from "${repo}": only GitHub repositories are named automatically, pass the name yourself.`);
+    }
+    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":"AAAA;;;;GAIG;AACH,MAAM,KAAW,QAAQ,CAiFxB;AAjFD,WAAiB,QAAQ;IAmBrB;;;OAGG;IACH,MAAM,eAAe,GAAG,sDAAsD,CAAC;IAE/E;;OAEG;IACH,MAAM,iBAAiB,GAAG,sGAAsG,CAAC;IAEjI;;;OAGG;IACH,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IAElC;;;;;;;;;;;;;;OAcG;IACH,SAAgB,IAAI,CAAC,IAAa;QAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,IAAI,IAAI,CAAC,CAAC;QAC3G,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,IAAI,2GAA2G,CAAC,CAAC;IAChP,CAAC;IAHe,SAAA,IAAI,OAGnB,CAAA;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAgB,WAAW,CAAC,IAAY;QACpC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QAC5C,IAAI,KAAK,EAAE,CAAC;YACR,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;YAClC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;YACtC,OAAO,GAAG,IAAI,IAAI,QAAQ,EAAE,CAAC;QACjC,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,8EAA8E,CAAC,CAAC;IACtI,CAAC;IATe,SAAA,WAAW,cAS1B,CAAA;AACL,CAAC,EAjFgB,QAAQ,KAAR,QAAQ,QAiFxB;AAED,eAAe,QAAQ,CAAC"}

package/dist/dependency/Dependency.d.ts

@@ -0,0 +1,81 @@
+import type Logger from "@netfeez/vterm";
+import schema from "../schema/schema.js";
+import type AliasCompiler from "../resolve/AliasCompiler.js";
+import type OutputPolicy from "../task/OutputPolicy.js";
+export declare abstract class Dependency {
+    readonly flowFolder: string;
+    readonly projectRoot: string;
+    /**
+     * The deadline every acquisition of a source runs under, in milliseconds. Acquisition is bounded so a
+     * repository that never answers is reported instead of waiting forever.
+     *
+     * @remarks It is not the deadline of a build step, which is the one the schema declares: a clone or an
+     * install of a large source legitimately takes longer than a build step, and cutting it at the build
+     * deadline would report a failure for work that is still on its way.
+     */
+    static readonly ACQUISITION_TIME_MS: number;
+    protected readonly logger: Logger | null;
+    protected readonly policy: OutputPolicy | null;
+    readonly name: string;
+    readonly builder: schema.Builder;
+    readonly resolver: AliasCompiler.Resolver;
+    /**
+     * Creates the dependency over the two roots it works between.
+     * @param flowFolder - The flow directory (`.depflow`) every checkout of the project lives in.
+     * @param projectRoot - The root of the project the artifacts of the dependency are meant to land in.
+     * @param info - The identity, the build pipeline and the resolver entries of the dependency.
+     * @param logger - Where the acquisition and the build of the dependency report to.
+     * @param policy - How the output of the commands the dependency runs is presented. Without it the
+     * dependency falls back to its logger, which streams the live output and says nothing else about it.
+     *
+     * @remarks The two roots are not the same and are not interchangeable: the flow folder owns the working
+     * copy of a dependency, the project root owns what the project consumes. A pipeline reads from the first
+     * and deposits into the second, which is why both travel together instead of one being derived from the
+     * other.
+     *
+     * @remarks The logger and the policy are not two ways of saying the same thing. The logger carries what
+     * the dependency decides to say about itself, and it says it whatever the user asked to be shown; the
+     * policy carries what the commands printed, and how much of it is shown depends on that. A dependency
+     * built through the CLI gets both, and a dependency built from a test gets neither.
+     */
+    constructor(flowFolder: string, projectRoot: string, info: Dependency.Info, logger?: Logger | null, policy?: OutputPolicy | null);
+    /**
+     * Resolves a folder of the dependency, relative to the flow folder, and guarantees it stays inside it.
+     * @param segments - The path of the folder inside the flow folder.
+     * @returns The normalized path of the folder.
+     * @throws { Error } When the segments escape the flow folder.
+     *
+     * @remarks A name is an identity, never a path: the schema rejects the ones that are not a single
+     * segment, and this is where the ones that reach a dependency any other way are stopped, before
+     * anything is cloned into them or removed from them.
+     */
+    protected resolve(...segments: string[]): string;
+    /**
+     * Whether the dependency is installed, which is the folder of its files being in place.
+     * @returns A promise resolving to `true` when the files of the dependency are there.
+     */
+    abstract isInstalled(): Promise<boolean>;
+    /**
+     * Install the dependency.
+     * This method should handle the installation process, such as downloading files, setting up configurations, etc.
+     */
+    abstract install(): Promise<void>;
+    /**
+     * Uninstall the dependency.
+     * This method should handle the uninstallation process, such as removing files, cleaning up configurations, etc.
+     */
+    abstract uninstall(): Promise<void>;
+    /**
+     * Build the dependency.
+     * This method should handle the build process, such as compiling code, bundling files, etc.
+     */
+    abstract build(): Promise<void>;
+}
+export declare namespace Dependency {
+    interface Info {
+        name: string;
+        builder?: schema.Builder;
+        resolver?: AliasCompiler.Resolver;
+    }
+}
+export default Dependency;

package/dist/dependency/Dependency.js

@@ -0,0 +1,71 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Base contract for installable dependencies with their build pipeline and resolver.
+ * @license Apache-2.0
+ */
+import { Path } from "@netfeez/common-node";
+export class Dependency {
+    flowFolder;
+    projectRoot;
+    /**
+     * The deadline every acquisition of a source runs under, in milliseconds. Acquisition is bounded so a
+     * repository that never answers is reported instead of waiting forever.
+     *
+     * @remarks It is not the deadline of a build step, which is the one the schema declares: a clone or an
+     * install of a large source legitimately takes longer than a build step, and cutting it at the build
+     * deadline would report a failure for work that is still on its way.
+     */
+    static ACQUISITION_TIME_MS = 300000;
+    logger;
+    policy;
+    name;
+    builder;
+    resolver;
+    /**
+     * Creates the dependency over the two roots it works between.
+     * @param flowFolder - The flow directory (`.depflow`) every checkout of the project lives in.
+     * @param projectRoot - The root of the project the artifacts of the dependency are meant to land in.
+     * @param info - The identity, the build pipeline and the resolver entries of the dependency.
+     * @param logger - Where the acquisition and the build of the dependency report to.
+     * @param policy - How the output of the commands the dependency runs is presented. Without it the
+     * dependency falls back to its logger, which streams the live output and says nothing else about it.
+     *
+     * @remarks The two roots are not the same and are not interchangeable: the flow folder owns the working
+     * copy of a dependency, the project root owns what the project consumes. A pipeline reads from the first
+     * and deposits into the second, which is why both travel together instead of one being derived from the
+     * other.
+     *
+     * @remarks The logger and the policy are not two ways of saying the same thing. The logger carries what
+     * the dependency decides to say about itself, and it says it whatever the user asked to be shown; the
+     * policy carries what the commands printed, and how much of it is shown depends on that. A dependency
+     * built through the CLI gets both, and a dependency built from a test gets neither.
+     */
+    constructor(flowFolder, projectRoot, info, logger, policy) {
+        this.flowFolder = flowFolder;
+        this.projectRoot = projectRoot;
+        this.name = info.name;
+        this.builder = info.builder || [];
+        this.resolver = info.resolver || {};
+        this.logger = logger || null;
+        this.policy = policy || null;
+    }
+    /**
+     * Resolves a folder of the dependency, relative to the flow folder, and guarantees it stays inside it.
+     * @param segments - The path of the folder inside the flow folder.
+     * @returns The normalized path of the folder.
+     * @throws { Error } When the segments escape the flow folder.
+     *
+     * @remarks A name is an identity, never a path: the schema rejects the ones that are not a single
+     * segment, and this is where the ones that reach a dependency any other way are stopped, before
+     * anything is cloned into them or removed from them.
+     */
+    resolve(...segments) {
+        const root = Path.normalize(this.flowFolder);
+        const folder = Path.normalize(Path.join(root, ...segments));
+        if (!Path.isInside(root, folder))
+            throw new Error(`Dependency "${this.name}" resolves outside of the flow folder: ${folder}`);
+        return folder;
+    }
+}
+export default Dependency;
+//# sourceMappingURL=Dependency.js.map