attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/file/directory.js

@@ -0,0 +1,141 @@
+/**
+ * Directory-node aggregation, Merkle fingerprints and flat listings.
+ *
+ * A directory fingerprint covers only structure: the ordered `(type, name,
+ * child fingerprint)` triples. Descriptions, summaries, purposes and timestamps
+ * are deliberately excluded, so adding an annotation or touching a timestamp
+ * cannot masquerade as a content change. The domain header `amp.fs.tree/1`
+ * keeps a tree digest from ever colliding with a raw file digest.
+ *
+ * Byte and line totals are summed as `bigint`; the wire projection turns them
+ * into decimal strings so a JSON transport cannot round them through 2^53.
+ */
+import { rawTextDigest } from "../fingerprint/raw.js";
+import { fail } from "./errors.js";
+import { wireTree } from "./file.js";
+import { annotationFor, describeDirectory, nameOfPath } from "./metadata.js";
+import { formatNodeTime } from "./time.js";
+const DefaultPageLimit = 50;
+const MaxPageLimit = 500;
+const compareNames = (left, right) => (left < right ? -1 : left > right ? 1 : 0);
+/**
+ * Tree ordering: directories first, then files, each group ascending by name.
+ *
+ * @param left - Left node.
+ * @param right - Right node.
+ * @returns Negative, zero or positive for ascending order.
+ */
+export const compareTreeNodes = (left, right) => {
+    if (left.type !== right.type) {
+        return left.type === "Directory" ? -1 : 1;
+    }
+    return compareNames(left.name, right.name);
+};
+const directoryFingerprint = (children) => {
+    const ordered = [...children].sort((left, right) => compareNames(left.name, right.name));
+    const parts = ["amp.fs.tree/1\n"];
+    for (let index = 0; index < ordered.length; index += 1) {
+        const child = ordered[index];
+        parts.push(`${child.type}\n${child.name}\n${child.fingerprint}\n`);
+    }
+    return rawTextDigest(parts.join(""));
+};
+const boundOffset = (value) => {
+    if (value === (void 0) || !Number.isFinite(value)) {
+        return 0;
+    }
+    return Math.max(0, Math.floor(value));
+};
+const boundLimit = (value) => {
+    if (value === (void 0) || Number.isNaN(value)) {
+        return DefaultPageLimit;
+    }
+    return Math.min(MaxPageLimit, Math.max(0, Math.floor(value)));
+};
+/**
+ * Build one directory node from already-built children.
+ *
+ * @param relative - Root-relative POSIX path.
+ * @param children - Direct children, in any order.
+ * @param options - Tree options (time zone and annotations).
+ * @param createdAt - Directory creation time when the caller has one.
+ * @param modifiedAt - Directory modification time when the caller has one.
+ * @returns An aggregated directory node.
+ */
+export const buildDirectoryNode = (relative, children, options = {}, createdAt, modifiedAt) => {
+    const timeZone = options.timeZone === "utc" ? "utc" : "local";
+    const ordered = [...children].sort(compareTreeNodes);
+    let bytes = 0n;
+    let lines = 0n;
+    let earliest;
+    let latest;
+    for (let index = 0; index < ordered.length; index += 1) {
+        const child = ordered[index];
+        bytes += child.bytes;
+        lines += child.lines;
+        if (earliest === (void 0) || child.create < earliest) {
+            earliest = child.create;
+        }
+        if (latest === (void 0) || child.modify > latest) {
+            latest = child.modify;
+        }
+    }
+    const epoch = formatNodeTime(new Date(0), timeZone);
+    const directoryModify = modifiedAt !== (void 0) ? formatNodeTime(modifiedAt, timeZone) : undefined;
+    const created = createdAt !== (void 0) ? formatNodeTime(createdAt, timeZone) : earliest ?? directoryModify ?? latest ?? epoch;
+    let modified = latest ?? created;
+    if (directoryModify !== (void 0) && directoryModify > modified) {
+        modified = directoryModify;
+    }
+    const described = describeDirectory(relative, ordered, annotationFor(options.annotations, relative));
+    return {
+        type: "Directory",
+        path: relative,
+        name: nameOfPath(relative),
+        extension: "directory",
+        children: ordered,
+        fingerprint: directoryFingerprint(ordered),
+        charset: "none",
+        lines,
+        bytes,
+        create: created,
+        modify: modified,
+        description: described.description,
+        summary: described.summary,
+        purpose: described.purpose,
+    };
+};
+/**
+ * Page through the direct children of one directory.
+ *
+ * Entries are projected with `wireTree(..., 0, ...)` so a listing never carries
+ * a nested subtree; the caller asks for a specific node when it needs one.
+ *
+ * @param tree - Workspace snapshot to read.
+ * @param path - Root-relative directory path.
+ * @param offset - Zero-based child offset.
+ * @param limit - Page size, capped at 500.
+ * @returns A bounded listing.
+ */
+export const listDirectory = (tree, path, offset = 0, limit = DefaultPageLimit) => {
+    const found = tree.node(path);
+    if (found === (void 0)) {
+        return fail("not_found");
+    }
+    if (found.type === "File") {
+        return fail("not_directory");
+    }
+    const ordered = [...found.children].sort(compareTreeNodes);
+    const total = ordered.length;
+    const start = boundOffset(offset);
+    const size = boundLimit(limit);
+    const page = ordered.slice(start, start + size);
+    const entries = page.map((child) => wireTree(child, 0, 0, 0));
+    return {
+        path: found.path,
+        revision: tree.revision(),
+        entries,
+        total,
+        nextOffset: start + page.length < total ? start + page.length : null,
+    };
+};

package/lib/file/errors.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Closed error taxonomy for the filesystem domain.
+ *
+ * Messages are the code itself. Host paths, specifiers and raw parser output
+ * stay out of the error string so a transport can forward it to a model
+ * without leaking the host layout.
+ */
+import type { FilesystemErrorCode } from "./types.js";
+export declare class FilesystemError extends Error {
+    readonly code: FilesystemErrorCode;
+    constructor(code: FilesystemErrorCode);
+}
+/**
+ * Throw one classified failure.
+ */
+export declare const fail: (code: FilesystemErrorCode) => never;
+/**
+ * Narrow an unknown thrown value to this domain's error.
+ */
+export declare const isFilesystemError: (error: unknown) => error is FilesystemError;

package/lib/file/errors.js

@@ -0,0 +1,18 @@
+export class FilesystemError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = "FilesystemError";
+        this.code = code;
+    }
+}
+/**
+ * Throw one classified failure.
+ */
+export const fail = (code) => {
+    throw new FilesystemError(code);
+};
+/**
+ * Narrow an unknown thrown value to this domain's error.
+ */
+export const isFilesystemError = (error) => error instanceof FilesystemError;

package/lib/file/exportGraph.d.ts

@@ -0,0 +1,31 @@
+import type { PathSandbox } from "./path.js";
+import type { ExportReport, ImportEdge } from "./types.js";
+/**
+ * A re-export edge.
+ *
+ * `ImportEdge` has no name field, and the filesystem types are frozen. The
+ * local subtype keeps the base edge contract intact while recording the
+ * exported name that the `reexports` array is meant to describe: `*` for a star
+ * re-export, the namespace name for `export * as ns`, and the exported name for
+ * `export { x } from`.
+ */
+export interface ReexportEdge extends ImportEdge {
+    readonly name: string;
+}
+type ExtractExportsFn = (sandbox: PathSandbox, path: string) => ExportReport;
+/**
+ * Extract exported symbols and re-export edges for one file.
+ *
+ * Declaration forms cover `function`, `class`, `interface`, `type`, `enum`,
+ * `const`, `let`, `var`, `namespace`/`module`, plus `export default`. Named
+ * clauses without a `from` resolve their kind from a local declaration when the
+ * scanner saw one and otherwise fall back to `const`; their signature is a
+ * normalized `export { ... }` clause. Files outside the JS/TS family return an
+ * empty report after the normal read/fingerprint checks.
+ *
+ * @param sandbox - Root-confined path resolver.
+ * @param path - Root-relative file path.
+ * @returns Export report for the file.
+ */
+export declare const extractExports: ExtractExportsFn;
+export {};