attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/outline/officeBridge.d.ts

@@ -0,0 +1,32 @@
+/** Office parser registration shared by strategies and the container adapter. */
+import type { OutlineNode } from "./types.js";
+/**
+ * Input the office parser receives. Office has no text lines of its own, so a
+ * parser numbers sections in document order and uses `bytes` for byte coverage.
+ */
+export interface OfficeOutlineInput {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+}
+/**
+ * Office section extractor. `office.ts` supplies the real implementation; until
+ * it is registered the skeleton returns an empty section list so an Office file
+ * still yields a valid file anchor instead of failing the whole tool.
+ */
+export type OfficeOutlineParser = (input: OfficeOutlineInput) => OutlineNode[];
+/**
+ * Register (or clear) the Office section extractor.
+ *
+ * @param parser - Extractor to use, or `undefined` to restore the empty
+ * skeleton.
+ */
+export declare const registerOfficeOutlineParser: (parser: OfficeOutlineParser | undefined) => void;
+/** Whether an Office section extractor is currently registered. */
+export declare const hasOfficeOutlineParser: () => boolean;
+/**
+ * Extract Office sections through the registered parser.
+ *
+ * @param input - Path and raw container bytes.
+ * @returns Section nodes in document order; empty when no parser is registered.
+ */
+export declare const parseOffice: (input: OfficeOutlineInput) => OutlineNode[];

package/lib/outline/officeBridge.js

@@ -0,0 +1,27 @@
+/**
+ * Mutable registration slot for the office extractor. A host calls
+ * `registerOfficeOutlineParser` once at startup; the slot keeps the mutation
+ * explicit instead of a module-level reassignable binding.
+ */
+const OfficeParserSlot = { parser: undefined };
+/**
+ * Register (or clear) the Office section extractor.
+ *
+ * @param parser - Extractor to use, or `undefined` to restore the empty
+ * skeleton.
+ */
+export const registerOfficeOutlineParser = (parser) => {
+    OfficeParserSlot.parser = parser;
+};
+/** Whether an Office section extractor is currently registered. */
+export const hasOfficeOutlineParser = () => OfficeParserSlot.parser !== (void 0);
+/**
+ * Extract Office sections through the registered parser.
+ *
+ * @param input - Path and raw container bytes.
+ * @returns Section nodes in document order; empty when no parser is registered.
+ */
+export const parseOffice = (input) => {
+    const parser = OfficeParserSlot.parser;
+    return parser === (void 0) ? [] : parser(input);
+};

package/lib/outline/outline.d.ts

@@ -0,0 +1,159 @@
+import type { OutlineMatchInput, OutlineStrategy } from "./strategy.js";
+import type { PathSandbox } from "../file/path.js";
+import type { DirectoryNode, FileNode } from "../file/types.js";
+import type { OutlineNode, OutlineResult } from "./types.js";
+/**
+ * Anchor objects a service can hand to the builder so it does not read or stat
+ * the same file twice. A mismatched path is ignored and the anchor is rebuilt.
+ */
+export interface OutlineAnchor {
+    readonly file?: FileNode;
+    readonly directory?: DirectoryNode;
+}
+/**
+ * One outline node that carries its own content fingerprint.
+ *
+ * `OutlineNode` in `types.ts` is owned by the shared contract; this projection
+ * adds the `fingerprint` property every emitted node has at runtime. Once the
+ * contract declares the field, the two types are identical.
+ */
+export type FingerprintedOutlineNode = OutlineNode & {
+    readonly fingerprint: string;
+};
+/**
+ * Read a node's fingerprint without requiring the contract type to declare it.
+ *
+ * @param node - Any outline node returned by `buildOutline`.
+ * @returns `sha256:<hex>` over the node's own text/byte range.
+ */
+export declare const outlineNodeFingerprint: (node: OutlineNode) => string;
+/**
+ * Options that bound an outline build. `maxNodes` and `maxDepth` are clamped
+ * rather than allowed to grow without limit; an invalid value is rejected as
+ * `invalid_arguments` so a caller cannot ask for "zero but infinite".
+ *
+ * For a directory target, `symbols` opts into expanding each direct child
+ * file's symbols; the default is anchors only, because a directory can hold
+ * more content than one tool result should carry.
+ */
+export interface OutlineOptions {
+    readonly maxNodes?: number;
+    readonly maxDepth?: number;
+    readonly symbols?: boolean;
+    readonly anchor?: OutlineAnchor;
+}
+export type { OutlineMatchInput, OutlineParseInput, OutlineStrategy } from "./strategy.js";
+/**
+ * Largest file an outline will load, in bytes. The whole file is decoded so
+ * the fingerprint and the charset are trustworthy; beyond this ceiling the
+ * caller should read selected pages instead of asking for structure.
+ */
+export declare const OutlineMaxFileBytes: number;
+/**
+ * Number of leading lines a structure scan keeps. The bound protects a single
+ * pathological file from dominating a turn; `truncated` makes the loss visible.
+ */
+export declare const OutlineMaxScanLines: number;
+/**
+ * Default and hard bounds for the node budget.
+ */
+export declare const OutlineDefaultMaxNodes: number;
+export declare const OutlineHardMaxNodes: number;
+/**
+ * Default and hard bounds for the depth ceiling.
+ */
+export declare const OutlineDefaultMaxDepth: number;
+export declare const OutlineHardMaxDepth: number;
+/**
+ * Stable lowercase language tag for a path. A file without an extension (or
+ * with only a dot-file name) answers `text`, matching the fallback contract.
+ *
+ * @param path - Root-relative or absolute path.
+ * @returns Lowercase extension without the dot, or `text`.
+ */
+export declare const outlineLanguage: (path: string) => string;
+/**
+ * Registry of outline strategies.
+ *
+ * Registration order is selection priority. A registry without a strategy that
+ * matches still returns a well-formed empty result instead of throwing, so an
+ * unknown file type is a cheap "nothing structured here" answer.
+ */
+export declare class OutlineRegistry {
+    private readonly strategies;
+    private readonly byId;
+    constructor(strategies?: readonly OutlineStrategy[]);
+    /**
+     * Append one strategy. Duplicate ids are rejected at registration time so a
+     * later lookup can never be ambiguous.
+     *
+     * @param strategy - Strategy to add.
+     */
+    register(strategy: OutlineStrategy): void;
+    /**
+     * Strategies in selection order.
+     */
+    list(): readonly OutlineStrategy[];
+    /**
+     * First registered strategy that matches, with the plain-text strategy as a
+     * deliberate fallback.
+     *
+     * @param input - Path, base name and content head.
+     * @returns The selected strategy, or `undefined` when the registry has no
+     * plain-text fallback.
+     */
+    select(input: OutlineMatchInput): OutlineStrategy | undefined;
+    /**
+     * Resolve, read, decode and outline one path.
+     *
+     * The order is strict: sandbox resolution, target-type dispatch, regular
+     * file checks, byte ceiling, sandbox revalidation, charset sniff, decode,
+     * strategy selection, parse and bounded finalization.
+     *
+     * @param sandbox - Session sandbox that owns path resolution.
+     * @param path - Root-relative POSIX path; a root-id prefix is accepted by
+     * the sandbox.
+     * @param options - Node/depth bounds, symbol expansion and an optional anchor.
+     * @param anchor - Anchor objects supplied by the service, overriding
+     * `options.anchor`.
+     * @returns The outline, including the whole-file fingerprint and charset.
+     */
+    build(sandbox: PathSandbox, path: string, options?: OutlineOptions, anchor?: OutlineAnchor): OutlineResult;
+    private buildFile;
+    private buildOffice;
+    private buildDirectory;
+    private directoryNodeFor;
+    private expandChildFile;
+}
+/**
+ * Registry with every built-in strategy, in selection priority order.
+ *
+ * The PascalCase binding is the project's top-level-data convention; the
+ * lowerCamel alias is the service-facing name.
+ */
+/**
+ * React precedes TypeScript/JavaScript because all three claim `.tsx`/`.jsx`;
+ * React only wins when the file carries React evidence, so plain TSX still falls
+ * through to the TypeScript strategy.
+ */
+export declare const DefaultOutlineRegistry: OutlineRegistry;
+export { DefaultOutlineRegistry as defaultOutlineRegistry };
+/**
+ * Snapshot of the default selection order, useful for a service catalog.
+ */
+export declare const OutlineStrategies: readonly OutlineStrategy[];
+/**
+ * Create an empty registry without built-ins. A host registers the strategies
+ * it trusts and then calls `build` exactly like the default registry.
+ */
+export declare const createOutlineRegistry: () => OutlineRegistry;
+/**
+ * Build the default outline for one workspace path.
+ *
+ * @param sandbox - Session sandbox that owns path resolution.
+ * @param path - Root-relative POSIX path.
+ * @param options - Node/depth bounds, symbol expansion and an optional anchor.
+ * @param anchor - Anchor objects supplied by the service.
+ * @returns The outline result.
+ */
+export declare const buildOutline: (sandbox: PathSandbox, path: string, options?: OutlineOptions, anchor?: OutlineAnchor) => OutlineResult;