attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/file/file.js

@@ -0,0 +1,339 @@
+/**
+ * File-node construction and wire projection.
+ *
+ * A file node is self-describing: its fingerprint covers every byte, while the
+ * descriptive metadata is derived from a bounded head. Large files therefore
+ * stay cheap to fingerprint (a streaming SHA-256 over 1 MiB chunks) without
+ * loading them into memory. Charset detection and line counting are delegated
+ * to `charset.ts` so the tree, the reader and the writer cannot disagree about
+ * what a line is.
+ *
+ * Every host path stays inside this module. Callers supply a root-relative POSIX
+ * path and receive detached metadata; errors are code-only.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, lstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { countLines, decodeText, detectCharset } from "../syntax/charset.js";
+import { fail } from "./errors.js";
+import { annotationFor, describeFile, extensionOfPath, nameOfPath } from "./metadata.js";
+import { PathSandbox } from "./path.js";
+import { creationTime, formatNodeTime } from "./time.js";
+const HeadBytes = 64 * 1024;
+const LargeFileBytes = 32 * 1024 * 1024;
+const ChunkBytes = 1024 * 1024;
+const NewlineByte = 0x0a;
+const ZeroByte = 0x00;
+const ControlCharacters = /[\u0000-\u001f\u007f]/;
+const DriveLetter = /^[A-Za-z]:/;
+const errnoCode = (error) => {
+    if (typeof (error) === "object" && error !== null) {
+        const candidate = error;
+        if (typeof (candidate.code) === "string") {
+            return candidate.code;
+        }
+    }
+    return "";
+};
+const failRead = (error) => {
+    const code = errnoCode(error);
+    if (code === "ENOENT" || code === "ENOTDIR") {
+        return fail("not_found");
+    }
+    if (code === "EACCES" || code === "EPERM") {
+        return fail("permission_denied");
+    }
+    if (code === "EISDIR") {
+        return fail("not_file");
+    }
+    if (code === "ELOOP") {
+        return fail("symlink_denied");
+    }
+    return fail("internal_error");
+};
+const normalizeFileRelative = (relative) => {
+    if (typeof (relative) !== "string" || ControlCharacters.test(relative)) {
+        return fail("invalid_path");
+    }
+    const text = relative.trim();
+    if (text.length === 0) {
+        return fail("not_file");
+    }
+    if (text.includes("\\")) {
+        return fail("invalid_path");
+    }
+    if (isAbsolute(text) || DriveLetter.test(text) || text.startsWith("//")) {
+        return fail("invalid_path");
+    }
+    const segments = [];
+    const parts = text.split("/");
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
+        if (part === "" || part === ".") {
+            continue;
+        }
+        if (part === "..") {
+            return fail("path_escape");
+        }
+        segments.push(part);
+    }
+    if (segments.length === 0) {
+        return fail("not_file");
+    }
+    return segments.join("/");
+};
+const absoluteOf = (root, relative) => join(root.path, ...relative.split("/"));
+const linkTargetStat = (root, absolute, linkStat, options) => {
+    if (!linkStat.isSymbolicLink()) {
+        return linkStat;
+    }
+    if (options.followSymlinks !== true) {
+        return fail("symlink_denied");
+    }
+    let real;
+    try {
+        real = realpathSync(absolute);
+    }
+    catch (error) {
+        return failRead(error);
+    }
+    const sandbox = new PathSandbox([root], { followSymlinks: true });
+    if (!sandbox.contains(root.path, real)) {
+        return fail("path_escape");
+    }
+    try {
+        return statSync(real);
+    }
+    catch (error) {
+        return failRead(error);
+    }
+};
+const concatBytes = (parts) => {
+    let total = 0;
+    for (let index = 0; index < parts.length; index += 1) {
+        total += parts[index].length;
+    }
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (let index = 0; index < parts.length; index += 1) {
+        result.set(parts[index], offset);
+        offset += parts[index].length;
+    }
+    return result;
+};
+const tallyChunk = (tally, chunk) => {
+    for (let index = 0; index < chunk.length; index += 1) {
+        if (chunk[index] === NewlineByte) {
+            tally.lf += 1n;
+        }
+    }
+    for (let index = 0; index + 1 < chunk.length; index += 2) {
+        if (chunk[index] === NewlineByte && chunk[index + 1] === ZeroByte) {
+            tally.le += 1n;
+        }
+        if (chunk[index] === ZeroByte && chunk[index + 1] === NewlineByte) {
+            tally.be += 1n;
+        }
+    }
+    if (chunk.length > 0) {
+        tally.previous = chunk.length > 1 ? chunk[chunk.length - 2] : tally.tail;
+        tally.tail = chunk[chunk.length - 1];
+    }
+};
+const readFileBytes = (absolute, size) => {
+    const collect = size <= LargeFileBytes;
+    const chunks = [];
+    const headParts = [];
+    const tally = { lf: 0n, le: 0n, be: 0n, previous: -1, tail: -1 };
+    const hasher = createHash("sha256");
+    const fd = openSync(absolute, "r");
+    let position = 0;
+    let headLength = 0;
+    try {
+        while (position < size) {
+            const length = Math.min(ChunkBytes, size - position);
+            const buffer = Buffer.allocUnsafe(length);
+            const read = readSync(fd, buffer, 0, length, position);
+            if (read <= 0) {
+                break;
+            }
+            const chunk = buffer.subarray(0, read);
+            hasher.update(chunk);
+            if (collect) {
+                chunks.push(chunk);
+            }
+            else {
+                tallyChunk(tally, chunk);
+            }
+            if (headLength < HeadBytes) {
+                const take = Math.min(HeadBytes - headLength, chunk.length);
+                headParts.push(chunk.subarray(0, take));
+                headLength += take;
+            }
+            position += read;
+        }
+    }
+    finally {
+        closeSync(fd);
+    }
+    return {
+        head: concatBytes(headParts),
+        full: collect ? concatBytes(chunks) : undefined,
+        fingerprint: `sha256:${hasher.digest("hex")}`,
+        tally,
+    };
+};
+const countStreamedLines = (charset, size, tally) => {
+    if (size === 0 || charset === "binary" || charset === "none") {
+        return 0n;
+    }
+    if (charset === "utf-16le") {
+        const endsWithNewline = tally.previous === NewlineByte && tally.tail === ZeroByte;
+        return tally.le + (endsWithNewline ? 0n : 1n);
+    }
+    if (charset === "utf-16be") {
+        const endsWithNewline = tally.previous === ZeroByte && tally.tail === NewlineByte;
+        return tally.be + (endsWithNewline ? 0n : 1n);
+    }
+    return tally.lf + (tally.tail === NewlineByte ? 0n : 1n);
+};
+const timeZoneOf = (options) => (options.timeZone === "utc" ? "utc" : "local");
+/**
+ * Build one file node by stat-ing and reading the file behind a root-relative
+ * path.
+ *
+ * @param root - Session root that owns the file.
+ * @param relative - Root-relative POSIX path.
+ * @param options - Tree bounds and metadata options.
+ * @returns A file node with a full-content fingerprint.
+ */
+export const buildFileNode = (root, relative, options = {}) => {
+    const path = normalizeFileRelative(relative);
+    const absolute = absoluteOf(root, path);
+    const rootExclude = Array.isArray(root.exclude) ? root.exclude : [];
+    const optionExclude = Array.isArray(options.exclude) ? options.exclude : [];
+    const scopedRoot = { ...root, exclude: [...rootExclude, ...optionExclude] };
+    const sandbox = new PathSandbox([scopedRoot], { followSymlinks: options.followSymlinks === true });
+    if (sandbox.isExcluded(scopedRoot, path)) {
+        return fail("excluded_path");
+    }
+    sandbox.revalidate({ root: scopedRoot, relative: path, absolute });
+    let linkStat;
+    try {
+        linkStat = lstatSync(absolute);
+    }
+    catch (error) {
+        return failRead(error);
+    }
+    const stat = linkTargetStat(scopedRoot, absolute, linkStat, options);
+    if (!stat.isFile()) {
+        return fail("not_file");
+    }
+    let read;
+    try {
+        read = readFileBytes(absolute, stat.size);
+    }
+    catch (error) {
+        return failRead(error);
+    }
+    const body = read.full;
+    const detected = detectCharset(body ?? read.head);
+    let charset = detected.binary ? "binary" : detected.charset;
+    let lines = 0n;
+    if (charset !== "binary") {
+        if (body !== (void 0)) {
+            try {
+                lines = countLines(decodeText(body, charset));
+            }
+            catch {
+                charset = "binary";
+                lines = 0n;
+            }
+        }
+        else {
+            lines = countStreamedLines(charset, stat.size, read.tally);
+        }
+    }
+    const described = describeFile(absolute, path, charset, read.head, annotationFor(options.annotations, path));
+    const timeZone = timeZoneOf(options);
+    const create = formatNodeTime(creationTime(stat), timeZone);
+    const modify = formatNodeTime(new Date(stat.mtimeMs), timeZone);
+    return {
+        type: "File",
+        path,
+        name: nameOfPath(path),
+        extension: extensionOfPath(path),
+        children: [],
+        fingerprint: read.fingerprint,
+        charset,
+        lines,
+        bytes: BigInt(stat.size),
+        create,
+        modify,
+        description: described.description,
+        summary: described.summary,
+        purpose: described.purpose,
+    };
+};
+const wireFile = (node) => ({
+    ...node,
+    lines: `${node.lines}`,
+    bytes: `${node.bytes}`,
+    children: [],
+});
+const wireDirectory = (node, children) => ({
+    ...node,
+    lines: `${node.lines}`,
+    bytes: `${node.bytes}`,
+    children,
+});
+/**
+ * Project an in-process node into its JSON-safe wire shape. `lines`/`bytes`
+ * become decimal strings and every descendant is projected as well.
+ *
+ * @param node - Node to project.
+ * @returns Wire node.
+ */
+export const wireNode = (node) => {
+    if (node.type === "File") {
+        return wireFile(node);
+    }
+    return wireDirectory(node, node.children.map((child) => wireNode(child)));
+};
+/**
+ * Project a node with a bounded number of child levels. `depth` 0 returns the
+ * node with an empty child list, which is what a flat directory listing needs.
+ *
+ * @param node - Node to project.
+ * @param depth - Maximum child levels to include.
+ * @param offset - Child offset at the first level.
+ * @param limit - Maximum children at the first level.
+ * @returns Wire node.
+ */
+export const wireTree = (node, depth, offset, limit) => {
+    if (node.type === "File") {
+        return wireFile(node);
+    }
+    const levels = Number.isFinite(depth) ? Math.max(0, Math.floor(depth)) : depth > 0 ? Number.MAX_SAFE_INTEGER : 0;
+    if (levels === 0) {
+        return wireDirectory(node, []);
+    }
+    const start = Number.isFinite(offset) ? Math.max(0, Math.floor(offset)) : 0;
+    const size = Number.isFinite(limit) ? Math.max(0, Math.floor(limit)) : node.children.length;
+    const selected = node.children.slice(start, start + size);
+    return wireDirectory(node, selected.map((child) => wireTree(child, levels - 1, 0, Number.MAX_SAFE_INTEGER)));
+};
+/**
+ * Re-read a file and fail unless its content fingerprint matches the expected
+ * value. The whole file is hashed; no partial comparison is attempted.
+ *
+ * @param root - Session root that owns the file.
+ * @param relative - Root-relative POSIX path.
+ * @param expected - Expected `sha256:<hex>` reference.
+ */
+export const verifyFingerprint = (root, relative, expected) => {
+    const node = buildFileNode(root, relative);
+    if (node.fingerprint !== expected) {
+        return fail("fingerprint_mismatch");
+    }
+};

package/lib/file/importGraph.d.ts

@@ -0,0 +1,121 @@
+import type { PathSandbox } from "./path.js";
+import type { ImportEdge, ImportReport } from "./types.js";
+/**
+ * One file read through a sandbox. `path` is root-relative and the fingerprint
+ * covers the exact bytes that were measured, so a caller can persist the report
+ * against the same content address a tree node would use.
+ */
+export interface SourceFileSnapshot {
+    readonly path: string;
+    readonly fingerprint: string;
+    readonly text: string;
+}
+/**
+ * One lexical token. `value` is decoded for string literals and raw for
+ * identifiers, punctuation and templates. `line` is 1-based.
+ */
+export interface SourceToken {
+    readonly kind: "identifier" | "string" | "template" | "punct";
+    readonly value: string;
+    readonly line: number;
+}
+/**
+ * Result of resolving one specifier from one root-relative file.
+ *
+ * `resolved` means a file was found for a relative specifier, or that the
+ * specifier is external and therefore intentionally not probed. `to` is the
+ * resolved root-relative path for internal specifiers, the bare specifier for
+ * external ones, and the unchanged absolute specifier for `/...`.
+ */
+export interface ResolvedSpecifier {
+    readonly to: string;
+    readonly resolved: boolean;
+    readonly external: boolean;
+}
+type ReadSourceFileFn = (sandbox: PathSandbox, path: string) => SourceFileSnapshot;
+type ResolveImportSpecifierFn = (sandbox: PathSandbox, from: string, specifier: string) => ResolvedSpecifier;
+type ExtractImportsFn = (sandbox: PathSandbox, path: string) => ImportReport;
+type ImportedByFn = (sandbox: PathSandbox, target: string, candidates: readonly string[]) => ImportEdge[];
+/**
+ * Read one sandboxed file for import/export extraction.
+ *
+ * The size limit is checked before the read and again after it: a file that
+ * grows between the two checks is refused rather than silently truncated. A
+ * binary charset is refused because slicing it as text would produce nonsense
+ * tokens. Errors carry a code only, never a host path.
+ *
+ * @param sandbox - Root-confined path resolver.
+ * @param path - Root-relative file path.
+ * @returns Decoded text, root-relative path and content fingerprint.
+ */
+export declare const readSourceFile: ReadSourceFileFn;
+/**
+ * Whether the extension is one of the JS/TS family the lexical scanner covers.
+ */
+export declare const isParseableSource: (path: string) => boolean;
+/**
+ * Whether the extension may contain JSX syntax. JSX-aware tokenization is
+ * enabled only for `.tsx`/`.jsx`; plain `.ts` keeps `<...>` as generic/type
+ * punctuation so type parameters are not mistaken for elements.
+ */
+export declare const isJsxSource: (path: string) => boolean;
+/**
+ * Tokenize JavaScript/TypeScript well enough to find module keywords.
+ *
+ * Comments, strings, template literal text, JSX text and regular-expression
+ * literals are consumed as opaque units, which is what makes pseudo-imports in
+ * those regions invisible. `${...}` expressions inside a template and
+ * `{...}` expressions inside JSX are tokenized recursively, so a real dynamic
+ * import there is still reported. The scanner is not a full lexer:
+ * regex-versus-division is resolved by attempting to close a regex before a
+ * newline or semicolon; a lone division slash falls back to punctuation, and a
+ * regex candidate never manufactures an edge because its body stays opaque.
+ *
+ * @param text - Decoded source text.
+ * @param jsx - Whether JSX elements should be skipped as opaque regions.
+ * @returns Tokens in source order, with 1-based line numbers.
+ */
+export declare const tokenizeSource: (text: string, jsx?: boolean) => SourceToken[];
+/**
+ * Resolve one import specifier against a root-relative source file.
+ *
+ * Relative specifiers are normalized (never allowed to climb above the root)
+ * and probed as exact path, extensionless, then directory index. An unresolved
+ * relative specifier still reports a guessed path so a caller can show what was
+ * tried; absolute specifiers keep their original spelling and stay unresolved;
+ * bare specifiers are external by definition, including `node:*`.
+ *
+ * @param sandbox - Root-confined path resolver used for existence checks.
+ * @param from - Root-relative path of the importing file.
+ * @param specifier - Raw specifier text.
+ * @returns Target path plus resolved/external flags.
+ */
+export declare const resolveImportSpecifier: ResolveImportSpecifierFn;
+/**
+ * Extract module edges for one file.
+ *
+ * Supported forms are static imports (including side-effect imports), type-only
+ * imports, `export ... from`, dynamic `import()` and `require()`. Files with a
+ * non-JS/TS extension are still read and fingerprinted but produce an empty
+ * edge list. `importedBy` is left empty for the service/graph layer to fill.
+ *
+ * @param sandbox - Root-confined path resolver.
+ * @param path - Root-relative file path.
+ * @returns Import report for the file.
+ */
+export declare const extractImports: ExtractImportsFn;
+/**
+ * Build the reverse edge list for one target from a set of candidate files.
+ *
+ * Candidates that cannot be read (missing, binary, over quota) are skipped
+ * rather than failing the whole reverse lookup: one unreadable file must not
+ * make "who imports this?" unavailable. Duplicate edges are removed while
+ * preserving candidate order.
+ *
+ * @param sandbox - Root-confined path resolver.
+ * @param target - Root-relative target file.
+ * @param candidates - Root-relative files to inspect.
+ * @returns Edges that resolve to `target`.
+ */
+export declare const importedBy: ImportedByFn;
+export {};