attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/hook/index.js

@@ -0,0 +1,23 @@
+/**
+ * Public surface of the hook layer.
+ *
+ * The concrete `use*` hooks and their shared types are exported here. Each
+ * module has its own `useParse` read helper, so those collide by design; they
+ * are re-exported under module-qualified names (`useCodeParse`,
+ * `useProjectParse`, ...) and the original name remains available from the
+ * module itself.
+ *
+ * `createHook` is re-exported explicitly because it is the extension point a
+ * host uses to add a hook without changing this package.
+ */
+export * from "./types.js";
+export * from "./diff.js";
+export * from "./file.js";
+export { createHook } from "./types.js";
+export { useDependency, useParse as useDependencyParse } from "./dependency.js";
+export { useExportation, useParse as useExportationParse } from "./exportation.js";
+export { useImportation, useParse as useImportationParse } from "./importation.js";
+export { useOutline, useParse as useOutlineParse } from "./outline.js";
+export { useAst, useParse as useAstParse } from "./ast.js";
+export { useCode, useParse as useCodeParse } from "./code.js";
+export { projectKindOf, useProject, useParse as useProjectParse } from "./project.js";

package/lib/hook/outline.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Outline hooks.
+ *
+ * The parse helper accepts the full filesystem `OutlineOptions`, but only the
+ * options the service request can express are forwarded: `maxNodes`,
+ * `maxDepth` and `symbols`. `anchor` is an internal optimisation the service
+ * owns and a caller cannot supply through the tool surface, so it is ignored
+ * rather than forging a cached node.
+ *
+ * `useOutline` forwards the complete `OutlineRequest`, including `query`,
+ * `startLine` and `endLine`, because those are caller-visible filters.
+ */
+import type { OutlineOptions } from "../outline/outline.js";
+import type { OutlineRequest } from "../file/service.js";
+import type { OutlineResult } from "../outline/types.js";
+import type { Hook, HookOptions, HookSession } from "./types.js";
+/**
+ * Parse helper shape. `options` bounds the outline; `anchor` is not forwarded.
+ */
+export type OutlineParse = (path: string, options?: OutlineOptions) => OutlineResult;
+/**
+ * Read the outline of one file or directory.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export declare const useParse: (session: HookSession) => OutlineParse;
+/**
+ * Outline hook.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing one outline result.
+ */
+export declare const useOutline: (session: HookSession, options?: HookOptions) => Hook<OutlineRequest, OutlineResult>;

package/lib/hook/outline.js

@@ -0,0 +1,27 @@
+import { createHook } from "./types.js";
+/**
+ * Read the outline of one file or directory.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export const useParse = (session) => (path, options = {}) => session.outline({
+    path,
+    ...(options.maxNodes === (void 0) ? {} : { maxNodes: options.maxNodes }),
+    ...(options.maxDepth === (void 0) ? {} : { maxDepth: options.maxDepth }),
+    ...(options.symbols === (void 0) ? {} : { symbols: options.symbols }),
+});
+/**
+ * Outline hook.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing one outline result.
+ */
+export const useOutline = (session, options = {}) => createHook({
+    name: "outline",
+    session,
+    execute: (request) => session.outline(request),
+    pathOf: (request) => request.path,
+    options,
+});

package/lib/hook/project.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Project manifest hook.
+ *
+ * A project model answers the three questions an agent has before reading a
+ * build file: which ecosystem is this, what is it called and what does it
+ * declare. The ecosystem is a pure function of the file name. The name and
+ * version are extracted with the smallest possible parser: `JSON.parse` for
+ * `package.json` and a line regex for TOML manifests. A failed or missing
+ * manifest simply leaves those two fields out; it never fails the model,
+ * because the outline and the dependency report are still useful.
+ *
+ * `manifestOutline` comes from `session.outline` and `dependencies` from
+ * `session.dependency` with the manifest path as the root. Both are read-only;
+ * the hook layer never runs a package manager, a build tool or a resolver.
+ */
+import type { DependencyReport } from "../file/types.js";
+import type { OutlineResult } from "../outline/types.js";
+import type { Hook, HookOptions, HookSession } from "./types.js";
+/**
+ * Build ecosystem recognized by the project hook.
+ */
+export type ProjectKind = "npm" | "maven" | "gradle" | "cmake" | "cargo" | "go" | "python" | "make" | "unknown";
+/**
+ * Model of one project manifest.
+ */
+export interface ProjectModel {
+    readonly path: string;
+    readonly kind: ProjectKind;
+    readonly name?: string;
+    readonly version?: string;
+    readonly manifestOutline: OutlineResult;
+    readonly dependencies: DependencyReport;
+}
+/**
+ * Request accepted by `useProject`.
+ */
+export interface ProjectRequest {
+    readonly path: string;
+}
+/**
+ * Parse helper shape: one manifest path in, one project model out.
+ */
+export type ProjectParse = (path: string) => ProjectModel;
+/**
+ * Recognize a project manifest by file name.
+ *
+ * @param path - Root-relative path.
+ * @returns Ecosystem tag, or `unknown`.
+ */
+export declare const projectKindOf: (path: string) => ProjectKind;
+/**
+ * Read the project model for one manifest path.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export declare const useParse: (session: HookSession) => ProjectParse;
+/**
+ * Project hook.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing one project model.
+ */
+export declare const useProject: (session: HookSession, options?: HookOptions) => Hook<ProjectRequest, ProjectModel>;

package/lib/hook/project.js

@@ -0,0 +1,217 @@
+import { createHook } from "./types.js";
+/**
+ * Leading lines read for name/version extraction. Manifests put their identity
+ * near the top; a larger read would only add latency to a model that does not
+ * otherwise need the text.
+ */
+const ManifestLines = 400;
+/**
+ * Byte budget for the same read.
+ */
+const ManifestBytes = 256 * 1024;
+/**
+ * Manifest file name to ecosystem. The map is exact-case; `makefile` and
+ * `GNUmakefile` are included because GNU make accepts them as canonical names.
+ */
+const ProjectKinds = new Map([
+    ["package.json", "npm"],
+    ["pom.xml", "maven"],
+    ["build.gradle", "gradle"],
+    ["build.gradle.kts", "gradle"],
+    ["CMakeLists.txt", "cmake"],
+    ["Cargo.toml", "cargo"],
+    ["go.mod", "go"],
+    ["pyproject.toml", "python"],
+    ["Makefile", "make"],
+    ["makefile", "make"],
+    ["GNUmakefile", "make"],
+]);
+/**
+ * TOML sections that are allowed to declare the package identity. Dependency
+ * tables also contain `name` keys (for example a Cargo dependency alias), so a
+ * section check is what keeps a dependency from renaming the project.
+ */
+const IdentitySections = new Set(["package", "project", "tool.poetry", "tool.pdm", "tool.flit.metadata"]);
+/**
+ * TOML table header, single or array form.
+ */
+const TomlSection = /^\s*\[\[?([^\]]+)\]\]?\s*(?:#.*)?$/;
+/**
+ * TOML `name`/`version` assignment with a basic or literal string value.
+ */
+const TomlField = /^\s*(name|version)\s*=\s*(?:"([^"]*)"|'([^']*)')\s*(?:#.*)?$/;
+/**
+ * Leaf name of a root-relative path.
+ *
+ * @param path - POSIX path.
+ * @returns Last segment.
+ */
+const baseNameOf = (path) => {
+    const slash = path.lastIndexOf("/");
+    return slash === -1 ? path : path.slice(slash + 1);
+};
+/**
+ * Recognize a project manifest by file name.
+ *
+ * @param path - Root-relative path.
+ * @returns Ecosystem tag, or `unknown`.
+ */
+export const projectKindOf = (path) => ProjectKinds.get(baseNameOf(path)) ?? "unknown";
+/**
+ * Extract `name`/`version` from a JSON manifest. A malformed document or a
+ * non-string field is ignored rather than reported.
+ *
+ * @param text - Whole manifest text.
+ * @returns Identity fields that were present as non-empty strings.
+ */
+const jsonIdentity = (text) => {
+    try {
+        const value = JSON.parse(text);
+        if (value === null || typeof (value) !== "object" || Array.isArray(value)) {
+            return {};
+        }
+        const record = value;
+        const name = record.name;
+        const version = record.version;
+        return {
+            ...(typeof (name) === "string" && name.length > 0 ? { name } : {}),
+            ...(typeof (version) === "string" && version.length > 0 ? { version } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+};
+/**
+ * Extract `name`/`version` from a TOML manifest with a section-aware line
+ * scanner. This stays a deliberate simplification (no multi-line strings or
+ * dotted keys), but it accepts both TOML string forms and only reads the
+ * `[package]`/`[project]`/poetry tables, so a dependency named `name` cannot
+ * shadow the project identity.
+ *
+ * @param text - Whole manifest text.
+ * @returns Identity fields that were present.
+ */
+const tomlIdentity = (text) => {
+    let section = "";
+    let name;
+    let version;
+    const lines = text.split("\n");
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index];
+        const sectionMatch = TomlSection.exec(line);
+        if (sectionMatch !== null) {
+            section = sectionMatch[1].trim();
+            continue;
+        }
+        if (!IdentitySections.has(section)) {
+            continue;
+        }
+        const fieldMatch = TomlField.exec(line);
+        if (fieldMatch === null) {
+            continue;
+        }
+        const value = fieldMatch[2] !== (void 0) ? fieldMatch[2] : fieldMatch[3];
+        if (value.length === 0) {
+            continue;
+        }
+        if (fieldMatch[1] === "name" && name === (void 0)) {
+            name = value;
+        }
+        else if (fieldMatch[1] === "version" && version === (void 0)) {
+            version = value;
+        }
+        if (name !== (void 0) && version !== (void 0)) {
+            break;
+        }
+    }
+    return {
+        ...(name === (void 0) ? {} : { name }),
+        ...(version === (void 0) ? {} : { version }),
+    };
+};
+/**
+ * Choose the identity extractor by ecosystem.
+ *
+ * @param kind - Recognized ecosystem.
+ * @param text - Manifest text, or `""` when it could not be read.
+ * @returns Identity fields.
+ */
+const identityOf = (kind, text) => {
+    if (text.length === 0) {
+        return {};
+    }
+    switch (kind) {
+        case "npm": {
+            return jsonIdentity(text);
+        }
+        case "cargo":
+        case "python": {
+            return tomlIdentity(text);
+        }
+        default: {
+            return {};
+        }
+    }
+};
+/**
+ * Read the declaration text of a manifest, returning `""` on any failure. The
+ * outline call that follows still surfaces a missing or unreadable file, so
+ * this swallow only affects the optional name/version fields.
+ *
+ * @param session - Bound filesystem session.
+ * @param path - Root-relative manifest path.
+ * @returns Decoded text or `""`.
+ */
+const readManifest = (session, path) => {
+    try {
+        const page = session.read({ path, maxLines: ManifestLines, maxBytes: ManifestBytes });
+        return page.text;
+    }
+    catch {
+        return "";
+    }
+};
+/**
+ * Assemble one project model.
+ *
+ * @param session - Bound filesystem session.
+ * @param path - Root-relative manifest path.
+ * @returns Project model.
+ */
+const projectModelOf = (session, path) => {
+    const kind = projectKindOf(path);
+    const text = kind === "unknown" ? "" : readManifest(session, path);
+    const identity = identityOf(kind, text);
+    const manifestOutline = session.outline({ path });
+    const dependencies = session.dependency({ mode: "dependencies", roots: [path] });
+    return {
+        path,
+        kind,
+        ...(identity.name === (void 0) ? {} : { name: identity.name }),
+        ...(identity.version === (void 0) ? {} : { version: identity.version }),
+        manifestOutline,
+        dependencies,
+    };
+};
+/**
+ * Read the project model for one manifest path.
+ *
+ * @param session - Bound filesystem session.
+ * @returns Parse helper.
+ */
+export const useParse = (session) => (path) => projectModelOf(session, path);
+/**
+ * Project hook.
+ *
+ * @param session - Bound filesystem session.
+ * @param options - Recorder and cache options.
+ * @returns Hook producing one project model.
+ */
+export const useProject = (session, options = {}) => createHook({
+    name: "project",
+    session,
+    execute: (request) => projectModelOf(session, request.path),
+    pathOf: (request) => request.path,
+    options,
+});

package/lib/hook/types.d.ts

@@ -0,0 +1,114 @@
+import type { FilesystemSession } from "../file/service.js";
+import type { FilesystemToolErrorCode } from "../protocol/filesystem.js";
+/**
+ * Lifecycle of one hook. `ready` and `error` are both terminal for a single
+ * `run`; a later `run` starts again from `loading`.
+ */
+export type HookStatus = "idle" | "loading" | "ready" | "error";
+/**
+ * Error surface of a hook. Domain failures keep their filesystem/session code;
+ * a malformed hook request is reported as `invalid_arguments`.
+ */
+export type HookErrorCode = FilesystemToolErrorCode | "invalid_arguments";
+/**
+ * Observable hook state. `revision` is the workspace revision the value (or
+ * failure) was observed at; an `idle` state keeps the revision of the previous
+ * run so a caller does not lose the coordinate when resetting a view.
+ *
+ * @typeParam T - Value produced by a successful run.
+ */
+export interface HookState<T> {
+    readonly status: HookStatus;
+    readonly value?: T;
+    readonly error?: HookErrorCode;
+    readonly revision: string;
+}
+/**
+ * One audit row for a hook run. Digests are `sha256:` values of the canonical
+ * request and (on success) the canonical output; `startedAt` is an ISO
+ * timestamp and `durationMs` is wall-clock milliseconds.
+ */
+export interface HookRunEntry {
+    readonly hook: string;
+    readonly sessionId: string;
+    readonly path?: string;
+    readonly status: HookStatus;
+    readonly error?: HookErrorCode;
+    readonly revision: string;
+    readonly startedAt: string;
+    readonly durationMs: number;
+    readonly inputDigest: string;
+    readonly outputDigest: string;
+}
+/**
+ * Persistence port for run entries. A recorder is fire-and-forget from the
+ * hook's point of view: the hook catches recorder failures so an audit sink
+ * outage cannot turn a successful read into a failed one.
+ */
+export interface HookRecorder {
+    record(entry: HookRunEntry): void;
+}
+/**
+ * Per-hook options. `cache` is opt-in because a request-only cache key cannot
+ * know that a file changed on disk; hosts that enable it accept that trade-off.
+ * `maxCacheEntries` is clamped to a positive bound instead of being trusted.
+ */
+export interface HookOptions {
+    readonly recorder?: HookRecorder;
+    readonly cache?: boolean;
+    readonly maxCacheEntries?: number;
+}
+/**
+ * The slice of `FilesystemSession` a hook needs. Kept as a structural `Pick`
+ * instead of importing the concrete class so a test double with the same typed
+ * methods works, and so the dependency direction stays `hook -> filesystem`.
+ */
+export type HookSession = Pick<FilesystemSession, "sessionId" | "descriptor" | "read" | "write" | "outline" | "imports" | "exports" | "dependency" | "ast" | "revision">;
+/**
+ * One observable hook. `run` returns the state it produced, which lets a caller
+ * use the direct return value without waiting for the subscription callback.
+ *
+ * @typeParam TRequest - Request accepted by `run`.
+ * @typeParam TResult - Value produced by a successful run.
+ */
+export interface Hook<TRequest, TResult> {
+    readonly state: HookState<TResult>;
+    run(request: TRequest): Promise<HookState<TResult>>;
+    subscribe(listener: (state: HookState<TResult>) => void): () => void;
+    reset(): void;
+}
+/**
+ * Definition consumed by {@link createHook}. `pathOf` supplies the optional
+ * path recorded in the run entry; `revisionOf` overrides the default revision
+ * read (`session.revision()`), which is what a write needs because its result
+ * already carries the post-write revision.
+ *
+ * @typeParam TRequest - Request accepted by `run`.
+ * @typeParam TResult - Value produced by a successful run.
+ */
+export interface HookDefinition<TRequest, TResult> {
+    readonly name: string;
+    readonly session: HookSession;
+    readonly execute: (request: TRequest) => TResult | Promise<TResult>;
+    readonly pathOf?: (request: TRequest) => string | undefined;
+    readonly revisionOf?: (result: TResult) => string;
+    readonly options?: HookOptions;
+}
+/**
+ * Factory shape of {@link createHook}.
+ *
+ * @typeParam TRequest - Request accepted by `run`.
+ * @typeParam TResult - Value produced by a successful run.
+ */
+export type HookFactory = <TRequest, TResult>(definition: HookDefinition<TRequest, TResult>) => Hook<TRequest, TResult>;
+/**
+ * Create one observable hook from a definition. This is the shared factory the
+ * concrete `use*` hooks are built on.
+ *
+ * @typeParam TRequest - Request accepted by `run`.
+ * @typeParam TResult - Value produced by a successful run.
+ * @param definition - Name, session, executor, optional revision/path mapping
+ * and options.
+ * @returns A hook with state, subscription, reset and bounded caching.
+ */
+export declare const createHook: HookFactory;