attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/outline/strategy.d.ts

@@ -0,0 +1,46 @@
+/** Contracts for pure, replayable outline strategies. */
+import type { LineIndex } from "../syntax/charset.js";
+import type { OutlineCategory, OutlineNode } from "./types.js";
+/**
+ * Input a strategy matcher sees. `head` is the first few KiB of decoded text so
+ * a content-sniffing matcher never needs the whole file.
+ */
+export interface OutlineMatchInput {
+    readonly path: string;
+    readonly name: string;
+    readonly head: string;
+}
+/**
+ * Input a strategy parser sees. `text` may be a 3000-line prefix of the file
+ * when the file is larger; `lineIndex` indexes exactly that text. Line numbers
+ * are therefore still 1-based and still point at the original file as long as
+ * the caller did not scan past the prefix.
+ */
+export interface OutlineParseInput {
+    readonly path: string;
+    readonly text: string;
+    readonly lineIndex: LineIndex;
+    /**
+     * Report that the parser hit its own bounded scan limit and the returned
+     * symbols are incomplete. The registry folds this into `truncated`, so a
+     * strategy-level cap (for example the HTML tag budget) stays visible even
+     * when the node and depth budgets were not reached.
+     */
+    readonly markTruncated?: () => void;
+}
+/**
+ * One outline parser. `id` is the stable strategy tag written to
+ * `OutlineResult.strategy`; `category` is the coarse family used for
+ * rendering. `language` is optional because a plain-text file answers with its
+ * extension instead of a language name.
+ *
+ * A parser returns symbols only; the registry assigns the anchor path and the
+ * byte range from the symbol's line numbers.
+ */
+export interface OutlineStrategy {
+    readonly id: string;
+    readonly category: OutlineCategory;
+    readonly language?: string;
+    readonly matches: (input: OutlineMatchInput) => boolean;
+    readonly parse: (input: OutlineParseInput) => OutlineNode[];
+}

package/lib/outline/strategy.js

@@ -0,0 +1 @@
+export {};

package/lib/outline/types.d.ts

@@ -0,0 +1,95 @@
+import type { Charset, SourceRange } from "../syntax/types.js";
+import type { FileNode, DirectoryNode, WireFileNode, WireDirectoryNode } from "../file/types.js";
+/**
+ * Outline symbol kinds. The set is intentionally language-neutral; a renderer
+ * can group by `language` and `kind` without learning a new enum per parser.
+ */
+export type OutlineKind = "heading" | "part" | "chapter" | "section" | "subsection" | "paragraph" | "class" | "interface" | "type" | "enum" | "namespace" | "struct" | "trait" | "object" | "module" | "function" | "method" | "property" | "constant" | "variable" | "component" | "hook" | "props" | "jsx" | "key" | "environment" | "reference" | "package" | "dependency" | "plugin" | "target" | "task" | "script" | "workspace" | "profile" | "macro";
+/**
+ * Broad outline family. The `strategy` field on the result is the precise
+ * parser; the category lets a caller render a code tree differently from a
+ * project model or a book's table of contents without knowing every strategy.
+ */
+export type OutlineCategory = "code" | "project" | "prose" | "data" | "other";
+/** Source coordinates shared with the syntax layer. */
+export type OutlineRange = SourceRange;
+/**
+ * Node type. File/Directory anchor an outline to a tree object; the remaining
+ * values are symbol kinds inside that object.
+ */
+export type OutlineType = "File" | "Directory" | OutlineKind;
+/**
+ * One outline node.
+ *
+ * The same shape describes a tree object and a symbol:
+ * - a file anchor has `isFile: true`, `file` set, `path: "add.py"`, `type: "File"`;
+ * - a directory anchor has `isDirectory: true`, `directory` set, `path: "src"`,
+ *   `type: "Directory"`;
+ * - a symbol has both flags false, no `file`/`directory`, a `path` such as
+ *   `"add.py#add"` or `"add.py#Numerical.solve"`, and a symbol `type`.
+ *
+ * `file`/`directory` are optional so a symbol does not repeat a whole node and
+ * a caller can decide whether it needs the anchor object.
+ */
+export interface OutlineNode {
+    readonly isFile: boolean;
+    readonly isDirectory: boolean;
+    readonly file?: FileNode;
+    readonly directory?: DirectoryNode;
+    readonly path: string;
+    readonly type: OutlineType;
+    readonly range: OutlineRange;
+    readonly label: string;
+    readonly depth: number;
+    /**
+     * Declaration modifiers in source order, e.g. `["static"]`,
+     * `["public", "readonly"]`. Empty/absent means no modifier.
+     */
+    readonly modifiers?: readonly string[];
+    readonly detail?: string;
+    readonly children: readonly OutlineNode[];
+}
+/**
+ * Outline extraction result. `language` is a stable lowercase tag such as
+ * `markdown`, `typescript`, `json`, `css` or `tex`; `strategy` is the precise
+ * parser (for example `maven` or `plainText`); `target` says whether the root
+ * anchor is a file or a directory.
+ */
+export interface OutlineResult {
+    readonly path: string;
+    readonly fingerprint: string;
+    readonly language: string;
+    readonly strategy: string;
+    readonly category: OutlineCategory;
+    readonly target: "file" | "directory";
+    readonly charset: Charset;
+    readonly nodes: readonly OutlineNode[];
+    readonly truncated: boolean;
+}
+/**
+ * JSON projection of an `OutlineRange`. Byte/line values become decimal
+ * strings because JSON has no bigint; a reader restores them with `BigInt`.
+ */
+export interface WireOutlineRange {
+    readonly startByte: string;
+    readonly endByte: string;
+    readonly startLine: string;
+    readonly endLine: string;
+}
+/**
+ * JSON projection of an outline node. `file`/`directory` anchors use the same
+ * wire projection as the `file` tool, so a client has one parser for both.
+ */
+export interface WireOutlineNode extends Omit<OutlineNode, "file" | "directory" | "range" | "children"> {
+    readonly file?: WireFileNode;
+    readonly directory?: WireDirectoryNode;
+    readonly range: WireOutlineRange;
+    readonly children: readonly WireOutlineNode[];
+}
+/**
+ * JSON projection of a complete outline result, used by MCP responses and by
+ * the `file_outlines.data_json` column.
+ */
+export interface WireOutlineResult extends Omit<OutlineResult, "nodes"> {
+    readonly nodes: readonly WireOutlineNode[];
+}

package/lib/outline/types.js

@@ -0,0 +1 @@
+export {};

package/lib/outline/visualBasicOutline.d.ts

@@ -0,0 +1,27 @@
+import type { OutlineParseInput, OutlineStrategy } from "./strategy.js";
+import type { OutlineNode } from "./types.js";
+/**
+ * Parse Visual Basic source text.
+ *
+ * The walk is single pass with an `End` stack. Blocks come from the source's own
+ * delimiters: `Namespace`, `Class`, `Module`, `Structure`, `Interface` and
+ * `Enum` open containers, `Sub`/`Function`/`Property` open bodies, and the
+ * matching `End` line gives the node's `endLine`. Members attach to the nearest
+ * open container, not to the nearest open body, so a property or method body
+ * never becomes a parent of the next member.
+ *
+ * @param input - Decoded VB text and its line index (the index is not needed by
+ * this line-based scanner, but the input contract requires it); `input.path`
+ * also decides whether untyped VBScript fields are accepted.
+ * @returns Namespace/type/member tree; an empty list for an empty file.
+ */
+export declare const parseVisualBasic: (input: OutlineParseInput) => OutlineNode[];
+/**
+ * Registry adapter for the VB parser.
+ *
+ * `id` is the stable strategy tag written to `OutlineResult.strategy` (camelCase
+ * like `plainText`); `language` is the stable lowercase tag written to
+ * `OutlineResult.language`. Both `.vb` and `.vbs` select this strategy, and
+ * `.vbproj` deliberately does not, so the XML project strategy keeps that file.
+ */
+export declare const VisualBasicStrategy: OutlineStrategy;