harnery 0.41.0 → 0.42.0

package/dist/lib/disk-usage.js

@@ -0,0 +1,303 @@
+import { spawnSync } from "node:child_process";
+import { lstatSync, readdirSync } from "node:fs";
+import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+export const DISK_GIT_STATES = [
+    "tracked",
+    "untracked",
+    "ignored",
+    "git-metadata",
+    "non-repository",
+    "unknown",
+];
+const TYPES = {
+    video: new Set(["mp4", "mov", "mkv", "webm", "avi", "m4v", "mxf"]),
+    audio: new Set(["mp3", "wav", "m4a", "aac", "flac", "ogg", "aiff"]),
+    image: new Set([
+        "png",
+        "jpg",
+        "jpeg",
+        "webp",
+        "gif",
+        "tif",
+        "tiff",
+        "svg",
+        "avif",
+        "heic",
+        "bmp",
+        "psd",
+    ]),
+    archive: new Set(["zip", "gz", "tgz", "tar", "bz2", "xz", "7z", "rar"]),
+};
+TYPES.media = new Set([...TYPES.video, ...TYPES.audio, ...TYPES.image]);
+const portable = (path) => path.split(sep).join("/");
+const empty = (allocated) => ({
+    files: 0,
+    apparent_bytes: 0,
+    allocated_bytes: allocated ? 0 : null,
+});
+export function parseDiskSize(value) {
+    const match = /^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB|TB|KiB|MiB|GiB|TiB)?$/i.exec(value);
+    if (!match)
+        throw new Error("--min-size requires bytes or a size such as 10MB or 1GiB");
+    const units = {
+        b: 1,
+        kb: 1e3,
+        mb: 1e6,
+        gb: 1e9,
+        tb: 1e12,
+        kib: 1024,
+        mib: 1024 ** 2,
+        gib: 1024 ** 3,
+        tib: 1024 ** 4,
+    };
+    const bytes = Number(match[1]) * units[(match[2] ?? "b").toLowerCase()];
+    if (!Number.isSafeInteger(bytes) || bytes < 0)
+        throw new Error("--min-size must resolve to a non-negative whole byte count");
+    return bytes;
+}
+/** Inspect regular files only. No bodies are read and no symlinks are followed. */
+export function diskUsage(input = ".", options = {}) {
+    const root = resolve(input);
+    const rootStat = lstatSync(root);
+    if (rootStat.isSymbolicLink() || (!rootStat.isDirectory() && !rootStat.isFile())) {
+        throw new Error("disk requires a regular file or directory, not a symlink or special file");
+    }
+    const group = options.group ?? "directory";
+    if (!["directory", "repository", "extension", "git", "files"].includes(group))
+        throw new Error("invalid --group; use directory, repository, extension, git, or files");
+    const depth = options.depth ?? 1;
+    const top = options.top ?? 20;
+    if (!Number.isSafeInteger(depth) || depth < 1)
+        throw new Error("--depth must be a positive integer");
+    if (!Number.isSafeInteger(top) || top < 1)
+        throw new Error("--top must be a positive integer");
+    if (options.minSize !== undefined &&
+        (!Number.isSafeInteger(options.minSize) || options.minSize < 0))
+        throw new Error("invalid --min-size");
+    const states = options.git ? new Set(options.git.split(",")) : null;
+    if (states && [...states].some((s) => !DISK_GIT_STATES.includes(s)))
+        throw new Error(`invalid --git; use ${DISK_GIT_STATES.join(", ")}`);
+    const extensions = options.type
+        ? new Set(options.type
+            .toLowerCase()
+            .split(",")
+            .flatMap((type) => [...(TYPES[type] ?? new Set([type.replace(/^\./, "")]))]))
+        : null;
+    const excludes = (options.exclude ?? [])
+        .flatMap((value) => value.split(","))
+        .map((value) => value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, ""));
+    if (excludes.some((value) => !value || isAbsolute(value) || value.split("/").includes("..")))
+        throw new Error("--exclude requires directory names or paths relative to the scan root");
+    let allocatedAvailable = process.platform !== "win32" && Number.isFinite(rootStat.blocks);
+    const report = {
+        schema: "harnery.disk-usage/v1",
+        root,
+        measurement: options.apparent
+            ? "apparent"
+            : allocatedAvailable
+                ? "allocated"
+                : "apparent-fallback",
+        complete: true,
+        filters: { ...options, group, depth, top },
+        totals: empty(allocatedAvailable),
+        git: Object.fromEntries(DISK_GIT_STATES.map((state) => [state, empty(allocatedAvailable)])),
+        groups: [],
+        group_count: 0,
+        largest_files: [],
+        repositories: [],
+        skipped: { symlinks: 0, special_files: 0, excluded: 0 },
+        issues: [],
+    };
+    const groups = new Map();
+    const repositories = new Map();
+    const seen = new Set();
+    const issue = (path, error) => {
+        report.complete = false;
+        report.issues.push({ path, message: error instanceof Error ? error.message : String(error) });
+    };
+    const git = (cwd, args) => spawnSync("git", ["-C", cwd, "-c", "core.fsmonitor=false", ...args], {
+        encoding: "utf8",
+        maxBuffer: 256 * 1024 * 1024,
+        timeout: 60_000,
+        windowsHide: true,
+    });
+    const loadRepo = (repoRoot) => {
+        const cached = repositories.get(repoRoot);
+        if (cached)
+            return cached;
+        const repo = {
+            root: repoRoot,
+            tracked: new Set(),
+            untracked: new Set(),
+            valid: false,
+        };
+        repositories.set(repoRoot, repo);
+        for (const [args, target] of [
+            [["ls-files", "--cached", "-z"], repo.tracked],
+            [["ls-files", "--others", "--exclude-standard", "-z"], repo.untracked],
+        ]) {
+            const result = git(repoRoot, [...args]);
+            if (result.status !== 0) {
+                issue(portable(relative(root, repoRoot)) || ".", result.error ?? new Error(`Git classification failed: ${result.stderr.trim()}`));
+                return repo;
+            }
+            for (const path of result.stdout.split("\0"))
+                if (path)
+                    target.add(path);
+        }
+        repo.valid = true;
+        return repo;
+    };
+    const startDir = rootStat.isDirectory() ? root : dirname(root);
+    const detected = git(startDir, ["rev-parse", "--show-toplevel"]);
+    if (detected.error)
+        issue(".", detected.error);
+    const initialRepo = detected.status === 0 ? loadRepo(resolve(detected.stdout.trim())) : null;
+    const repoLabel = (repo) => {
+        if (!repo)
+            return null;
+        const label = portable(relative(root, repo.root));
+        return !label || label === ".." || label.startsWith("../") ? "." : label;
+    };
+    const metric = (row) => options.apparent || row.allocated_bytes === null ? row.apparent_bytes : row.allocated_bytes;
+    const compare = (a, b) => metric(b) - metric(a) || a.path.localeCompare(b.path);
+    const add = (totals, size, allocated) => {
+        totals.files++;
+        totals.apparent_bytes += size;
+        if (totals.allocated_bytes !== null)
+            totals.allocated_bytes += allocated;
+    };
+    const excluded = (path) => excludes.some((value) => value.includes("/")
+        ? path === value || path.startsWith(`${value}/`)
+        : path.split("/").includes(value));
+    const file = (path, metadata, repo, inGit) => {
+        const rel = portable(relative(root, path)) || ".";
+        const extension = extname(path).slice(1).toLowerCase();
+        const repoPath = repo ? portable(relative(repo.root, path)) : "";
+        const state = inGit
+            ? "git-metadata"
+            : !repo
+                ? "non-repository"
+                : !repo.valid
+                    ? "unknown"
+                    : repo.tracked.has(repoPath)
+                        ? "tracked"
+                        : repo.untracked.has(repoPath)
+                            ? "untracked"
+                            : "ignored";
+        if ((states && !states.has(state)) || (extensions && !extensions.has(extension)))
+            return;
+        const blocksAvailable = process.platform !== "win32" && Number.isFinite(metadata.blocks);
+        if (!blocksAvailable)
+            allocatedAvailable = false;
+        const allocation = blocksAvailable ? metadata.blocks * 512 : metadata.size;
+        if ((options.apparent || !blocksAvailable ? metadata.size : allocation) < (options.minSize ?? 0))
+            return;
+        const identity = metadata.ino ? `${metadata.dev}:${metadata.ino}` : path;
+        const allocated = seen.has(identity) ? 0 : allocation;
+        seen.add(identity);
+        add(report.totals, metadata.size, allocated);
+        add(report.git[state], metadata.size, allocated);
+        const row = {
+            path: rel,
+            files: 1,
+            apparent_bytes: metadata.size,
+            allocated_bytes: blocksAvailable ? allocation : null,
+            git: state,
+            repository: repoLabel(repo),
+        };
+        report.largest_files.push(row);
+        report.largest_files.sort(compare);
+        if (report.largest_files.length > top)
+            report.largest_files.pop();
+        if (group === "files")
+            return;
+        const parts = rel.split("/");
+        const label = group === "git"
+            ? state
+            : group === "repository"
+                ? (repoLabel(repo) ?? "(non-repository)")
+                : group === "extension"
+                    ? extension
+                        ? `.${extension}`
+                        : "(no extension)"
+                    : parts.length > 1
+                        ? parts.slice(0, Math.min(depth, parts.length - 1)).join("/")
+                        : ".";
+        let bucket = groups.get(label);
+        if (!bucket) {
+            bucket = { path: label, ...empty(allocatedAvailable) };
+            groups.set(label, bucket);
+        }
+        add(bucket, metadata.size, allocated);
+    };
+    const walk = (dir, parentRepo, inGit) => {
+        let entries;
+        try {
+            // A directory can turn into a link between reading its parent and visiting it.
+            if (lstatSync(dir).isSymbolicLink()) {
+                report.skipped.symlinks++;
+                return;
+            }
+            entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+        }
+        catch (error) {
+            issue(portable(relative(root, dir)) || ".", error);
+            return;
+        }
+        const marker = entries.find((entry) => entry.name === ".git");
+        const repo = !inGit && marker && !marker.isSymbolicLink() ? loadRepo(dir) : parentRepo;
+        for (const entry of entries) {
+            const path = resolve(dir, entry.name);
+            const rel = portable(relative(root, path));
+            if (excluded(rel)) {
+                report.skipped.excluded++;
+                continue;
+            }
+            if (entry.isSymbolicLink()) {
+                report.skipped.symlinks++;
+                continue;
+            }
+            const gitMetadata = inGit || entry.name === ".git";
+            if (entry.isDirectory()) {
+                if (gitMetadata && states && !states.has("git-metadata"))
+                    continue;
+                walk(path, repo, gitMetadata);
+            }
+            else if (entry.isFile()) {
+                try {
+                    const metadata = lstatSync(path);
+                    if (metadata.isSymbolicLink())
+                        report.skipped.symlinks++;
+                    else if (metadata.isFile())
+                        file(path, metadata, repo, gitMetadata);
+                    else
+                        report.skipped.special_files++;
+                }
+                catch (error) {
+                    issue(rel, error);
+                }
+            }
+            else
+                report.skipped.special_files++;
+        }
+    };
+    const inMetadata = startDir.split(sep).includes(".git");
+    if (rootStat.isDirectory())
+        walk(root, initialRepo, inMetadata);
+    else if (!excluded("."))
+        file(root, rootStat, initialRepo, inMetadata || root.endsWith(`${sep}.git`));
+    if (!allocatedAvailable) {
+        report.totals.allocated_bytes = null;
+        for (const totals of Object.values(report.git))
+            totals.allocated_bytes = null;
+        for (const row of groups.values())
+            row.allocated_bytes = null;
+        report.measurement = options.apparent ? "apparent" : "apparent-fallback";
+    }
+    report.repositories = [...repositories.values()].map((repo) => repoLabel(repo)).sort();
+    report.group_count = group === "files" ? report.totals.files : groups.size;
+    report.groups =
+        group === "files" ? report.largest_files : [...groups.values()].sort(compare).slice(0, top);
+    return report;
+}

package/dist/lib/docs-lint.d.ts

@@ -25,6 +25,12 @@ export interface LintOpts {
     repo?: string;
     source?: DocsRepositorySource;
 }
+/**
+ * Detect whether a file declares itself an intentional monolith. The banner
+ * must sit in the first 10 lines of the body; leading YAML frontmatter does
+ * not count toward those lines, since a v2 header alone can fill them.
+ */
+export declare function isDeclaredMonolith(content: string): boolean;
 /** Detect whether a file carries lifecycle status in leading YAML frontmatter. */
 export declare function hasStatusHeader(path: string): boolean;
 export declare function runLint(opts: LintOpts): Promise<Violation[]>;

package/dist/lib/docs-lint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAiBA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,IAAI,CAMP;AAYD,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,2BAA2B,CAAC;AAEnC;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AA0GD,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AA8ND,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAkClE"}
+{"version":3,"file":"docs-lint.d.ts","sourceRoot":"","sources":["../../src/lib/docs-lint.ts"],"names":[],"mappings":"AAiBA,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GAAG,IAAI,CAMP;AAYD,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,2BAA2B,CAAC;AAEnC;;;;;;GAMG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAoGD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI3D;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAMrD;AA8ND,wBAAsB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAkClE"}

package/dist/lib/docs-lint.js

@@ -114,9 +114,14 @@ function findMarkdownFiles(view) {
     !EXCLUDED_PREFIXES.some((p) => f.startsWith(p) || f.includes(`/${p}`)) &&
         !EXTRA_EXCLUDED_PREFIXES.some((p) => f.startsWith(p) || f.includes(`/${p}`)));
 }
-/** Detect whether a file declares itself an intentional monolith */
-function isDeclaredMonolith(content) {
-    const head = content.split("\n").slice(0, 10).join("\n");
+/**
+ * Detect whether a file declares itself an intentional monolith. The banner
+ * must sit in the first 10 lines of the body; leading YAML frontmatter does
+ * not count toward those lines, since a v2 header alone can fill them.
+ */
+export function isDeclaredMonolith(content) {
+    const body = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "");
+    const head = body.split("\n").slice(0, 10).join("\n");
     return /INTENTIONAL-MONOLITH/i.test(head);
 }
 /** Detect whether a file carries lifecycle status in leading YAML frontmatter. */

package/dist/lib/guarded-remove.d.ts

@@ -0,0 +1,34 @@
+export interface RemoveOptions {
+    root: string;
+    recursive?: boolean;
+    yes?: boolean;
+    dryRun?: boolean;
+    /**
+     * Protected paths (Git metadata, credentials, Harnery state, SSH or GnuPG
+     * keys, a bare repository) the caller names for removal, one exact path
+     * each. A protected path that is not named is still refused.
+     */
+    allowProtected?: string[];
+    /** Directories whose own Git metadata and Harnery state may never be allowed (the live workspace). */
+    liveRoots?: string[];
+}
+export interface RemovalLink {
+    path: string;
+    /** What the link points to. It is removed as a link and never followed. */
+    target: string;
+}
+export interface RemovalReport {
+    schema: "harnery.removal/v1";
+    applied: boolean;
+    root: string;
+    targets: string[];
+    entries: number;
+    bytes: number;
+    /** Protected paths removed because the caller named them with allowProtected. */
+    protected: string[];
+    /** Symbolic links inside recursive targets, removed as links. */
+    links: RemovalLink[];
+}
+/** Permanent removal is deliberately limited to inspected, untracked local outputs. */
+export declare function guardedRemove(paths: string[], options: RemoveOptions, checkClaims?: (targets: string[]) => void): RemovalReport;
+//# sourceMappingURL=guarded-remove.d.ts.map

package/dist/lib/guarded-remove.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-remove.d.ts","sourceRoot":"","sources":["../../src/lib/guarded-remove.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iEAAiE;IACjE,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAKD,uFAAuF;AACvF,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,EAAE,aAAa,EACtB,WAAW,GAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,IAAe,GAClD,aAAa,CAyJf"}