attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/file/exportGraph.js

@@ -0,0 +1,554 @@
+/**
+ * Export extraction for the agent workspace.
+ *
+ * The report is intentionally declaration-level: an agent that is about to
+ * change a module surface needs names, kinds, a bounded signature and the
+ * re-export edges, not a full syntax tree. The scanner shares the lexical
+ * tokenizer used by import extraction so comments, strings and templates cannot
+ * manufacture an export.
+ *
+ * `export * from` and `export * as ns from` have no symbol name in TypeScript's
+ * own model, so they are recorded as re-export edges with the local name `*` or
+ * `ns`. A named re-export also produces one `ExportSymbol` per exported name,
+ * which is what a consumer of the report actually wants to enumerate.
+ */
+import { LineIndex } from "../syntax/charset.js";
+import { isJsxSource, isParseableSource, readSourceFile, resolveImportSpecifier, tokenizeSource } from "./importGraph.js";
+const MaxExports = 5000;
+const SignatureLimit = 200;
+const DeclarationKinds = new Map([
+    ["function", "function"],
+    ["class", "class"],
+    ["interface", "interface"],
+    ["type", "type"],
+    ["enum", "enum"],
+    ["const", "const"],
+    ["let", "let"],
+    ["var", "var"],
+    ["namespace", "namespace"],
+    ["module", "namespace"],
+]);
+const DeclarationModifiers = new Set(["async", "abstract", "declare"]);
+const StatementKeywords = new Set([
+    "export",
+    "import",
+    "const",
+    "let",
+    "var",
+    "function",
+    "class",
+    "interface",
+    "enum",
+    "namespace",
+]);
+const collapseWhitespace = (value) => value.replace(/\s+/g, " ").trim();
+const signatureAt = (index, line) => collapseWhitespace(index.slice(line, 1).text).slice(0, SignatureLimit);
+const isMemberAccess = (previous) => previous !== (void 0) && previous.kind === "punct" && (previous.value === "." || previous.value === "?");
+/**
+ * Collect local declaration kinds so `export { local }` can use the declaration
+ * kind instead of the `const` fallback. This is a name map, not scope analysis:
+ * duplicate names in nested scopes collapse to the last declaration, which is
+ * acceptable for a descriptive report.
+ */
+const collectDeclarations = (tokens) => {
+    const declarations = new Map();
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token.kind !== "identifier" || isMemberAccess(tokens[index - 1])) {
+            continue;
+        }
+        const kind = DeclarationKinds.get(token.value);
+        if (kind === (void 0)) {
+            continue;
+        }
+        let nameIndex = index + 1;
+        if (token.value === "function") {
+            const star = tokens[nameIndex];
+            if (star !== (void 0) && star.kind === "punct" && star.value === "*") {
+                nameIndex += 1;
+            }
+        }
+        const nameToken = tokens[nameIndex];
+        if (nameToken !== (void 0) && nameToken.kind === "identifier") {
+            declarations.set(nameToken.value, kind);
+        }
+    }
+    return declarations;
+};
+/**
+ * Parse the `{ a, b as c, type D }` part of an export clause.
+ */
+const parseNamedClause = (tokens, openIndex) => {
+    const entries = [];
+    let index = openIndex + 1;
+    let depth = 1;
+    while (index < tokens.length) {
+        const token = tokens[index];
+        if (token.kind === "punct") {
+            if (token.value === "{") {
+                depth += 1;
+            }
+            else if (token.value === "}") {
+                depth -= 1;
+                if (depth === 0) {
+                    return { entries, closeIndex: index };
+                }
+            }
+            index += 1;
+            continue;
+        }
+        if (depth !== 1 || token.kind !== "identifier") {
+            index += 1;
+            continue;
+        }
+        let local = token.value;
+        if (local === "type") {
+            const modified = tokens[index + 1];
+            if (modified !== (void 0) && modified.kind === "identifier" && modified.value !== "as") {
+                index += 1;
+                local = modified.value;
+            }
+        }
+        let exported = local;
+        const asToken = tokens[index + 1];
+        if (asToken !== (void 0) && asToken.kind === "identifier" && asToken.value === "as") {
+            const alias = tokens[index + 2];
+            if (alias !== (void 0) && alias.kind === "identifier") {
+                exported = alias.value;
+                index += 2;
+            }
+        }
+        entries.push({ local, exported });
+        index += 1;
+    }
+    return { entries, closeIndex: tokens.length };
+};
+/**
+ * Return the index just past a balanced binding pattern.
+ */
+const skipPatternEnd = (tokens, start) => {
+    const opener = tokens[start];
+    if (opener === (void 0) || opener.kind !== "punct") {
+        return start + 1;
+    }
+    let depth = 0;
+    for (let index = start; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token.kind !== "punct") {
+            continue;
+        }
+        if (token.value === "{" || token.value === "[" || token.value === "(") {
+            depth += 1;
+        }
+        else if (token.value === "}" || token.value === "]" || token.value === ")") {
+            depth -= 1;
+            if (depth === 0) {
+                return index + 1;
+            }
+        }
+    }
+    return tokens.length;
+};
+/**
+ * Collect binding names from a destructuring pattern.
+ *
+ * Shorthand bindings are collected, renamed bindings contribute the bound name
+ * rather than the property key, computed keys are skipped, and a default
+ * expression is skipped until the next top-level comma. This is a lexical
+ * approximation: defaults that themselves contain destructuring patterns are
+ * not interpreted.
+ */
+const collectBindingNames = (tokens, openIndex) => {
+    const names = [];
+    const opener = tokens[openIndex];
+    const objectPattern = opener !== (void 0) && opener.kind === "punct" && opener.value === "{";
+    let depth = 0;
+    let skippingDefault = false;
+    for (let index = openIndex; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token.kind === "punct") {
+            if (objectPattern && depth === 1 && token.value === "[") {
+                index = skipPatternEnd(tokens, index) - 1;
+                continue;
+            }
+            if (token.value === "{" || token.value === "[" || token.value === "(") {
+                depth += 1;
+                if (depth === 1) {
+                    skippingDefault = false;
+                }
+                continue;
+            }
+            if (token.value === "}" || token.value === "]" || token.value === ")") {
+                depth -= 1;
+                if (depth === 0) {
+                    break;
+                }
+                continue;
+            }
+            if (token.value === "=" && depth === 1) {
+                skippingDefault = true;
+                continue;
+            }
+            if (token.value === "," && depth === 1) {
+                skippingDefault = false;
+            }
+            continue;
+        }
+        if (skippingDefault || token.kind !== "identifier") {
+            continue;
+        }
+        const next = tokens[index + 1];
+        if (next !== (void 0) && next.kind === "punct" && next.value === ":") {
+            continue;
+        }
+        names.push(token.value);
+    }
+    return names;
+};
+const addExport = (list, symbol) => {
+    if (list.length >= MaxExports) {
+        return false;
+    }
+    list.push(symbol);
+    return true;
+};
+/**
+ * Guess whether `<` opens a type-argument list in an initializer. A comparison
+ * can look identical at the token level, so the caller treats the range as
+ * opaque only until a matching `>`; a failed match simply hides later
+ * declarators of the same statement rather than inventing export names.
+ */
+const isLikelyGenericOpen = (tokens, index) => {
+    const previous = tokens[index - 1];
+    const next = tokens[index + 1];
+    if (previous === (void 0) || next === (void 0)) {
+        return false;
+    }
+    const previousOk = previous.kind === "identifier" || (previous.kind === "punct" && (previous.value === ")" || previous.value === "]" || previous.value === ">"));
+    const nextOk = next.kind === "identifier" || (next.kind === "punct" && (next.value === "{" || next.value === "(" || next.value === "["));
+    return previousOk && nextOk;
+};
+/**
+ * Collect additional declarators after the first one in
+ * `export const a = 1, b = 2`. Depth is tracked so commas inside calls, arrays,
+ * objects, arrows and template expressions do not split a declarator, a
+ * heuristic angle-depth keeps generic arguments from leaking type names, and a
+ * following statement keyword terminates the scan when semicolons are absent.
+ */
+const collectFollowingDeclarators = (input) => {
+    const tokens = input.tokens;
+    const start = input.start;
+    const kind = input.kind;
+    const line = input.line;
+    const signature = input.signature;
+    const exports = input.exports;
+    let truncated = false;
+    let depth = 0;
+    let angleDepth = 0;
+    let expectBinding = false;
+    for (let index = start; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token.kind === "punct") {
+            if (depth === 0 && angleDepth > 0) {
+                if (token.value === ";") {
+                    return truncated;
+                }
+                if (token.value === "<") {
+                    angleDepth += 1;
+                }
+                else if (token.value === ">" && !(tokens[index - 1] !== (void 0) && tokens[index - 1].kind === "punct" && tokens[index - 1].value === "=")) {
+                    angleDepth -= 1;
+                }
+                continue;
+            }
+            if (depth === 0 && token.value === "<" && !expectBinding && isLikelyGenericOpen(tokens, index)) {
+                angleDepth = 1;
+                continue;
+            }
+            if (depth === 0 && expectBinding && (token.value === "{" || token.value === "[")) {
+                const names = collectBindingNames(tokens, index);
+                for (let nameIndex = 0; nameIndex < names.length; nameIndex += 1) {
+                    if (!addExport(exports, { name: names[nameIndex], kind, line, signature })) {
+                        truncated = true;
+                    }
+                }
+                index = skipPatternEnd(tokens, index) - 1;
+                expectBinding = false;
+                continue;
+            }
+            if (token.value === "{" || token.value === "[" || token.value === "(") {
+                depth += 1;
+                continue;
+            }
+            if (token.value === "}" || token.value === "]" || token.value === ")") {
+                if (depth === 0) {
+                    return truncated;
+                }
+                depth -= 1;
+                continue;
+            }
+            if (depth !== 0) {
+                continue;
+            }
+            if (token.value === ";") {
+                return truncated;
+            }
+            if (token.value === ",") {
+                expectBinding = true;
+                continue;
+            }
+            if (token.value === "=") {
+                expectBinding = false;
+            }
+            continue;
+        }
+        if (depth !== 0 || token.kind !== "identifier") {
+            continue;
+        }
+        if (!isMemberAccess(tokens[index - 1]) && StatementKeywords.has(token.value)) {
+            return truncated;
+        }
+        if (!expectBinding) {
+            continue;
+        }
+        if (!addExport(exports, { name: token.value, kind, line, signature })) {
+            truncated = true;
+        }
+        expectBinding = false;
+    }
+    return truncated;
+};
+const addReexport = (list, edge) => {
+    if (list.length >= MaxExports) {
+        return false;
+    }
+    list.push(edge);
+    return true;
+};
+const reexportEdge = (sandbox, from, specifier, name, line) => {
+    const resolution = resolveImportSpecifier(sandbox, from, specifier);
+    return {
+        from,
+        to: resolution.to,
+        specifier,
+        kind: "export-from",
+        line,
+        resolved: resolution.resolved,
+        external: resolution.external,
+        name,
+    };
+};
+const extractionFromTokens = (tokens, text, from, sandbox) => {
+    const exports = [];
+    const reexports = [];
+    const declarations = collectDeclarations(tokens);
+    const lineIndex = new LineIndex(text);
+    const braceDepth = new Array(tokens.length);
+    let currentDepth = 0;
+    for (let index = 0; index < tokens.length; index += 1) {
+        braceDepth[index] = currentDepth;
+        const token = tokens[index];
+        if (token.kind === "punct" && token.value === "{") {
+            currentDepth += 1;
+        }
+        else if (token.kind === "punct" && token.value === "}" && currentDepth > 0) {
+            currentDepth -= 1;
+        }
+    }
+    let truncated = false;
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token.kind !== "identifier" || token.value !== "export" || isMemberAccess(tokens[index - 1]) || braceDepth[index] !== 0) {
+            continue;
+        }
+        const line = token.line;
+        const signature = signatureAt(lineIndex, line);
+        let cursor = index + 1;
+        const prefixed = tokens[cursor];
+        if (prefixed !== (void 0) &&
+            prefixed.kind === "identifier" &&
+            prefixed.value === "type" &&
+            tokens[cursor + 1] !== (void 0) &&
+            tokens[cursor + 1].kind === "punct" &&
+            (tokens[cursor + 1].value === "{" || tokens[cursor + 1].value === "*")) {
+            cursor += 1;
+        }
+        const head = tokens[cursor];
+        if (head === (void 0)) {
+            continue;
+        }
+        if (head.kind === "identifier" && head.value === "default") {
+            if (!addExport(exports, { name: "default", kind: "default", line, signature })) {
+                truncated = true;
+            }
+            continue;
+        }
+        if (head.kind === "punct" && head.value === "*") {
+            let starCursor = cursor + 1;
+            let name = "*";
+            const asToken = tokens[starCursor];
+            if (asToken !== (void 0) && asToken.kind === "identifier" && asToken.value === "as") {
+                const namespace = tokens[starCursor + 1];
+                if (namespace !== (void 0) && namespace.kind === "identifier") {
+                    name = namespace.value;
+                    starCursor += 2;
+                }
+            }
+            const fromToken = tokens[starCursor];
+            const specToken = tokens[starCursor + 1];
+            if (fromToken === (void 0) ||
+                fromToken.kind !== "identifier" ||
+                fromToken.value !== "from" ||
+                specToken === (void 0) ||
+                specToken.kind !== "string") {
+                continue;
+            }
+            if (!addReexport(reexports, reexportEdge(sandbox, from, specToken.value, name, line))) {
+                truncated = true;
+            }
+            continue;
+        }
+        if (head.kind === "punct" && head.value === "{") {
+            const clause = parseNamedClause(tokens, cursor);
+            let fromIndex = -1;
+            const fromToken = tokens[clause.closeIndex + 1];
+            if (fromToken !== (void 0) && fromToken.kind === "identifier" && fromToken.value === "from") {
+                const specToken = tokens[clause.closeIndex + 2];
+                if (specToken !== (void 0) && specToken.kind === "string") {
+                    fromIndex = clause.closeIndex + 1;
+                }
+            }
+            if (fromIndex !== -1) {
+                const specifier = tokens[fromIndex + 1].value;
+                for (let entryIndex = 0; entryIndex < clause.entries.length; entryIndex += 1) {
+                    const entry = clause.entries[entryIndex];
+                    if (!addExport(exports, { name: entry.exported, kind: "reexport", line, signature, reexportFrom: specifier })) {
+                        truncated = true;
+                    }
+                    if (!addReexport(reexports, reexportEdge(sandbox, from, specifier, entry.exported, line))) {
+                        truncated = true;
+                    }
+                }
+                continue;
+            }
+            const rendered = [];
+            for (let entryIndex = 0; entryIndex < clause.entries.length; entryIndex += 1) {
+                const entry = clause.entries[entryIndex];
+                rendered.push(entry.local === entry.exported ? entry.local : `${entry.local} as ${entry.exported}`);
+            }
+            const signatureText = collapseWhitespace(`export { ${rendered.join(", ")} }`).slice(0, SignatureLimit);
+            for (let entryIndex = 0; entryIndex < clause.entries.length; entryIndex += 1) {
+                const entry = clause.entries[entryIndex];
+                const kind = declarations.get(entry.local) ?? "const";
+                if (!addExport(exports, { name: entry.exported, kind, line, signature: signatureText })) {
+                    truncated = true;
+                }
+            }
+            continue;
+        }
+        let keywordIndex = cursor;
+        while (keywordIndex < tokens.length) {
+            const candidate = tokens[keywordIndex];
+            if (candidate.kind !== "identifier" || !DeclarationModifiers.has(candidate.value)) {
+                break;
+            }
+            keywordIndex += 1;
+        }
+        const keyword = tokens[keywordIndex];
+        if (keyword === (void 0) || keyword.kind !== "identifier") {
+            continue;
+        }
+        let kind = DeclarationKinds.get(keyword.value);
+        let nameIndex = keywordIndex + 1;
+        if (kind !== (void 0) && keyword.value === "const") {
+            const enumToken = tokens[nameIndex];
+            if (enumToken !== (void 0) && enumToken.kind === "identifier" && enumToken.value === "enum") {
+                kind = "enum";
+                nameIndex += 1;
+            }
+        }
+        if (kind === (void 0)) {
+            continue;
+        }
+        if (keyword.value === "function") {
+            const star = tokens[nameIndex];
+            if (star !== (void 0) && star.kind === "punct" && star.value === "*") {
+                nameIndex += 1;
+            }
+        }
+        const nameToken = tokens[nameIndex];
+        if (nameToken === (void 0)) {
+            continue;
+        }
+        if (nameToken.kind === "punct" && (kind === "const" || kind === "let" || kind === "var") && (nameToken.value === "{" || nameToken.value === "[")) {
+            const bindingNames = collectBindingNames(tokens, nameIndex);
+            for (let bindingIndex = 0; bindingIndex < bindingNames.length; bindingIndex += 1) {
+                if (!addExport(exports, { name: bindingNames[bindingIndex], kind, line, signature })) {
+                    truncated = true;
+                }
+            }
+            if (collectFollowingDeclarators({
+                tokens,
+                start: skipPatternEnd(tokens, nameIndex),
+                kind,
+                line,
+                signature,
+                exports,
+            })) {
+                truncated = true;
+            }
+            continue;
+        }
+        if (nameToken.kind !== "identifier") {
+            continue;
+        }
+        if (!addExport(exports, { name: nameToken.value, kind, line, signature })) {
+            truncated = true;
+        }
+        if (collectFollowingDeclarators({
+            tokens,
+            start: nameIndex + 1,
+            kind,
+            line,
+            signature,
+            exports,
+        })) {
+            truncated = true;
+        }
+    }
+    return { exports, reexports, truncated };
+};
+/**
+ * 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 const extractExports = (sandbox, path) => {
+    const source = readSourceFile(sandbox, path);
+    if (!isParseableSource(source.path)) {
+        return {
+            path: source.path,
+            fingerprint: source.fingerprint,
+            exports: [],
+            reexports: [],
+            truncated: false,
+        };
+    }
+    const extraction = extractionFromTokens(tokenizeSource(source.text, isJsxSource(source.path)), source.text, source.path, sandbox);
+    return {
+        path: source.path,
+        fingerprint: source.fingerprint,
+        exports: extraction.exports,
+        reexports: extraction.reexports,
+        truncated: extraction.truncated,
+    };
+};

package/lib/file/file.d.ts

@@ -0,0 +1,40 @@
+import type { SessionRoot } from "../session/types.js";
+import type { FileNode, TreeNode, TreeOptions, WireTreeNode } from "./types.js";
+/**
+ * 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 declare const buildFileNode: (root: SessionRoot, relative: string, options?: TreeOptions) => FileNode;
+/**
+ * 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 declare const wireNode: (node: TreeNode) => WireTreeNode;
+/**
+ * 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 declare const wireTree: (node: TreeNode, depth: number, offset: number, limit: number) => WireTreeNode;
+/**
+ * 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 declare const verifyFingerprint: (root: SessionRoot, relative: string, expected: string) => void;