@docsworth/cli 0.0.0-stage → 0.3.0

package/dist/core/adopt.d.ts

@@ -0,0 +1,68 @@
+import { type Config } from "./config.js";
+import { UserError } from "./errors.js";
+import { unprefixed } from "./links.js";
+export { unprefixed };
+export declare class AdoptError extends UserError {
+}
+export interface AdoptOptions {
+    now: Date;
+    /** The owning team where CODEOWNERS doesn't name exactly one. */
+    team?: string;
+    /** `review_every` for pages without one (default 90d). */
+    reviewEvery?: string;
+    /** Report, and write nothing. */
+    dryRun?: boolean;
+}
+export interface AdoptResult {
+    dryRun: boolean;
+    /** Pages adopt changed (or would, on a dry run). */
+    adopted: string[];
+    /** Pages it had nothing to change on. */
+    unchanged: string[];
+    /** Pages, and symbolic links, it left as they are, and why. */
+    left: {
+        path: string;
+        reason: string;
+    }[];
+    /** What the team still has to do: a CODEOWNERS line, say. */
+    hints: string[];
+    /** Route links rewritten to relative `.md` links (R2). */
+    linksRewritten: number;
+    /** Links lint fails that adopt couldn't rewrite, as written, and why. */
+    linksLeft: {
+        path: string;
+        link: string;
+        why: string;
+    }[];
+    /** Keys added to the config's `frontmatter.extra_fields`: the adopted pages' unknown keys (R3). */
+    extraFields: string[];
+}
+/** The repo, its config and its knowledge root, by real path, each checked to be inside the repo (R9). */
+export interface RepoPaths {
+    repo: string;
+    config: Config;
+    configPath: string;
+    knowledge: string;
+}
+/** Whether `child` is `parent` or under it, by path components (so `/repo-other` isn't under `/repo`). */
+export declare function within(parent: string, child: string): boolean;
+/** R9's checks, before any page is read: the config and the knowledge root are inside the repo. */
+export declare function repoPaths(root: string, Err?: new (m: string) => Error, verb?: string): RepoPaths;
+/**
+ * Why a file with other hard links is left, or null: the other path could be anywhere,
+ * outside the repo too, and a write here would change the file there (R9).
+ */
+export declare function hardLinked(abs: string, verb: string): string | null;
+/** Why a symbolic link in the knowledge root is left. */
+export declare const symlinkReason: (verb: string) => string;
+/**
+ * The knowledge root's pages, as the loader finds them (directories starting with a dot
+ * skipped), by real path. It follows no symbolic link: the loader reads none, and a link is
+ * the one way a walk could leave the root (R9). A link that names a page or a directory is
+ * reported.
+ */
+export declare function walk(dir: string, out: {
+    files: string[];
+    symlinks: string[];
+}): void;
+export declare function adoptRepo(root: string, opts: AdoptOptions): AdoptResult;