approval-md 0.0.1 → 0.2.0

package/dist/src/core/agents-md.d.ts

@@ -0,0 +1,276 @@
+/**
+ * AGENTS.md permissions import (SPEC.md §2, §12) — turn permissions PROSE into
+ * a DRAFT policy block a human can read, correct, and confirm.
+ *
+ * SPEC.md §2 names the gap this closes: AGENTS.md files "routinely contain
+ * permissions sections splitting actions into 'allowed without prompting' and
+ * 'require approval first'", and "nothing checks". SPEC.md §12 gives the verb:
+ * `approval import agents-md` "parses ... permissions sections into draft
+ * policy classes for human confirmation".
+ *
+ * ## This module is deterministic, and there is no model in it
+ *
+ * Per CLAUDE.md's engineering invariants, routing and policy are pure
+ * deterministic code; LLMs are confined to language tasks. Reading a bullet
+ * list is a language task in appearance only — its OUTPUT is a permission
+ * document, so the mapping is a fixed, ordered, documented keyword table
+ * ({@link CLASS_TABLE}), not a judgement. The same bytes always produce the
+ * same draft, on any machine, with no network and no clock. An LLM-assisted
+ * `--suggest` (proposing classes for bullets this table cannot place) is a
+ * separate, opt-in, out-of-scope idea: it would be allowed to propose, never
+ * to decide.
+ *
+ * ## The grammar
+ *
+ * Input is CommonMark-ish markdown. The scanner is line-based:
+ *
+ * - **Fenced code blocks** (``` or ~~~, 3+ markers, indented at most 3 spaces)
+ *   are skipped entirely. A bullet inside an example block is an example.
+ * - **Headings** are ATX only: `^ {0,3}#{1,6}\s+text`, trailing `#`s stripped.
+ *   Setext headings are not recognised; the convention in the wild is ATX.
+ * - A heading whose text contains `permissions` (case-insensitive, at any
+ *   level) opens the **permissions region**. The region closes at the next
+ *   non-canonical heading whose level is less than or equal to the permissions
+ *   heading's level.
+ * - Three **canonical sub-headings** open a section, matched case-insensitively
+ *   against {@link SECTION_PHRASES} after normalisation (lowercased, markdown
+ *   emphasis and backticks stripped, whitespace collapsed, trailing `:`
+ *   dropped). They are recognised at ANY level and, deliberately, whether or
+ *   not a parent `Permissions` heading exists: the bare three-heading layout is
+ *   common in AGENTS.md files.
+ * - **Bullets** are `-` or `*` list items (`^\s*[-*]\s+`) appearing while a
+ *   section is open. A following line that is not blank, not a heading, not a
+ *   list item and not a fence is a **continuation** and is joined to the
+ *   previous bullet with a single space. Any heading closes the open section.
+ * - Every other line is ignored.
+ *
+ * Non-canonical headings seen inside the permissions region, and non-canonical
+ * headings that interrupt an open section, are reported in `ignored` rather
+ * than silently dropped: a heading the importer did not understand may be
+ * carrying permissions prose, and the human confirming the draft is the one who
+ * should decide.
+ *
+ * ## Fail closed
+ *
+ * A bullet the table cannot place is NOT guessed at and NOT dropped. It becomes
+ * an `unmapped` entry, is preserved verbatim as a comment in the draft, and is
+ * covered by `defaults.autonomy: manual` — the strictest outcome available.
+ * Likewise a source with no permissions section produces an empty draft (all
+ * classes manual by default) plus a warning, never a permissive one.
+ *
+ * ## The values draft
+ *
+ * Since APRV-240 the same file is scanned a second time for four optional
+ * headings ("what I value", "what good looks like", "how I like to work",
+ * "what I want from you") and their bullets are drafted into a
+ * ` ```yaml approval-values ` block (SPEC.md §5.3). Every bullet lands in
+ * `wants:`, and nothing is ever placed in `love:`, `like:` or `dislike:`.
+ * Grading is the human's act. This importer can see that a line was written
+ * down; it cannot see how much its author meant it, and a guessed grade would
+ * put words in their mouth inside the one block of `APPROVAL.md` that exists to
+ * carry their own.
+ *
+ * ## Namespaces
+ *
+ * SPEC.md §7 reserves top-level namespaces to the spec and lets implementations
+ * add sub-classes freely. The developer-workstation vocabulary this table emits
+ * (`vcs.*`, `deps.*`, `release.*`, `exec.*`, `network.*`, `policy.edit`) is not
+ * in the §7 table, which was written for life-admin side effects. That is a
+ * deliberate, visible property of a DRAFT: the classes are proposals a human
+ * renames or upstreams before confirming, and the draft says so in its header.
+ */
+/** Which prose section a bullet came from. */
+export type AgentsMdSection = "allowed" | "approval-first" | "never";
+/** SPEC.md §5.2 autonomy levels, strictest first. */
+export type Autonomy = "manual" | "supervised" | "autonomous";
+/** One list item of a permissions section. */
+export interface Bullet {
+    /** The bullet's text, continuation lines joined, marker stripped. */
+    text: string;
+    /** 1-based line number of the bullet's first line, for diagnostics. */
+    line: number;
+}
+/** The three recognised sections, each in source order. */
+export interface AgentsMdSections {
+    allowed: Bullet[];
+    approvalFirst: Bullet[];
+    never: Bullet[];
+}
+/** Result of {@link parseAgentsMd}. Pure function of the input bytes. */
+export interface AgentsMdParse {
+    sections: AgentsMdSections;
+    /** Headings the scanner met inside the permissions area and did not use. */
+    ignored: string[];
+    /** Human-facing notes; never a reason to relax anything. */
+    warnings: string[];
+}
+/**
+ * The class heuristic: an ORDERED, STABLE table. First match wins, and the
+ * order of this array IS the precedence. Each entry lists alternative keyword
+ * conjunctions; an alternative matches when every one of its keywords appears
+ * as a substring of the normalised bullet text.
+ *
+ * Ordering rules, so future edits stay principled:
+ *
+ * 1. The most consequential and most specific classes come first, because a
+ *    bullet naming several actions ("git push, merges to main, tag creation")
+ *    is placed by its first match and the safer placement is the broader,
+ *    more consequential class.
+ * 2. `network.call` precedes `deps.add` on purpose: "any network call beyond
+ *    package installs" contains "install" and is not a dependency bullet.
+ * 3. `vcs.push` precedes `vcs.push.main`: a bullet naming pushes generally
+ *    should govern all pushes, not only pushes to the default branch.
+ * 4. Generic verbs (`edit`, `read`) come last, since almost every bullet
+ *    contains one.
+ *
+ * Adding a keyword here changes what a draft proposes for existing files, so
+ * the table is pinned byte-for-byte by `tests/agents-md.test.ts` fixtures.
+ */
+export declare const CLASS_TABLE: ReadonlyArray<{
+    readonly cls: string;
+    readonly any: ReadonlyArray<readonly string[]>;
+}>;
+/** Text used for keyword matching: lowercased with whitespace collapsed. */
+export declare function normaliseBullet(text: string): string;
+/**
+ * The class this bullet proposes, or `null` when the table cannot place it.
+ *
+ * Deterministic, total, and side-effect free: the first entry of
+ * {@link CLASS_TABLE} with a satisfied keyword conjunction wins.
+ */
+export declare function classifyBullet(text: string): string | null;
+/**
+ * Parse the permissions region of an AGENTS.md-style document.
+ *
+ * Never throws. Pure function of `markdown`; see the module header for the
+ * grammar it accepts.
+ */
+export declare function parseAgentsMd(markdown: string): AgentsMdParse;
+/** Result of {@link parseValuesHeadings}. Pure function of the input bytes. */
+export interface ValuesDraft {
+    /** The recognised headings, normalised, in source order. */
+    headings: string[];
+    /** Bullets destined for `wants:`: truncated, deduped, capped. */
+    wants: string[];
+    /** Bullets past {@link VALUES_MAX_ITEMS}, kept so none is dropped silently. */
+    overflow: string[];
+    /** Human-facing notes; never a reason to relax anything. */
+    warnings: string[];
+}
+/**
+ * Collect the bullets under the optional values headings of an AGENTS.md-style
+ * document (SPEC.md §5.3).
+ *
+ * ## Everything goes to `wants`, and nothing is graded
+ *
+ * The values block has three standing grades (`love`, `like`, `dislike`) and
+ * one behavioural list (`wants`). This function fills `wants` and leaves the
+ * three grades empty, always. A grade is a statement of taste, and it is the
+ * human's to make: the source shows that a line was written under a heading, it
+ * does not show how strongly it was meant, and an importer that inferred
+ * "love" from an exclamation mark or a heading's wording would be putting words
+ * in its reader's mouth in the one block of `APPROVAL.md` that exists to carry
+ * theirs. `wants` is the honest destination for a bullet whose grade is
+ * unknown: it says the operator asked for something, which is exactly what a
+ * bullet under "what I want from you" demonstrates.
+ *
+ * ## The scan
+ *
+ * A second line-based pass over the same primitives {@link parseAgentsMd} uses,
+ * with the same rules: fenced code blocks are skipped whole (a bullet in an
+ * example block is an example), headings are ATX at any level, a values heading
+ * opens a section, any other heading closes one, and a non-blank line that is
+ * not a bullet, heading or fence is a continuation joined to the previous
+ * bullet with a single space.
+ *
+ * Never throws. No clock, no filesystem, no network.
+ */
+export declare function parseValuesHeadings(markdown: string): ValuesDraft;
+/** One proposed class rule, with the bullets that produced it. */
+export interface DraftClass {
+    cls: string;
+    autonomy: Autonomy;
+    /** Every bullet that mapped here, in source order. */
+    bullets: Array<{
+        text: string;
+        section: AgentsMdSection;
+    }>;
+    /** The bullet that decided the autonomy (strictest, earliest on ties). */
+    from: {
+        text: string;
+        section: AgentsMdSection;
+    };
+}
+/** A bullet the table could not place. Covered by `defaults.autonomy`. */
+export interface UnmappedBullet {
+    text: string;
+    section: AgentsMdSection;
+}
+/** Result of {@link importAgentsMd}: the draft, and everything it could not use. */
+export interface AgentsMdImport {
+    classes: DraftClass[];
+    unmapped: UnmappedBullet[];
+    ignored: string[];
+    warnings: string[];
+    /**
+     * The values headings the same source declared (APRV-240). Empty `headings`
+     * means the source declared none, and no values fence is rendered at all: an
+     * absent values block is a declaration in its own right (SPEC.md §5.3), and a
+     * draft of one would be this importer inventing the declaration.
+     */
+    values: ValuesDraft;
+}
+/**
+ * Parse and classify: the whole deterministic half of `approval import
+ * agents-md`. Emitting bytes is {@link renderDraftPolicy}'s job.
+ *
+ * Conflicts follow SPEC.md §5.2 "deny beats allow": when bullets from different
+ * sections claim the same class, the strictest autonomy wins and a warning
+ * names both bullets, because a class that appears in both an allow list and an
+ * approval list is a contradiction in the SOURCE that a human must resolve.
+ */
+export declare function importAgentsMd(markdown: string): AgentsMdImport;
+/** Info string of the machine-readable policy block (SPEC.md §5). */
+export declare const POLICY_INFO_STRING = "yaml approval-policy";
+/**
+ * Render the values draft, fenced (APRV-240).
+ *
+ * The argument is the whole {@link ValuesDraft} rather than its bullets alone,
+ * because the entries past the cap have to appear in the output as comments:
+ * the renderer needs to see what was left out in order to say so.
+ *
+ * Deterministic, like everything else here. Entries are emitted as
+ * double-quoted scalars via `JSON.stringify`, whose escapes are all valid YAML
+ * double-quoted escapes, so a bullet full of backticks, colons and `#` survives
+ * the round trip without the renderer having to reason about YAML quoting.
+ */
+export declare function renderFencedValuesDraft(draft: ValuesDraft, source: string): string;
+/**
+ * The fenced values draft for an import, or `null` when the source declared no
+ * values headings. The `--json` surface's `values_draft` field, verbatim.
+ */
+export declare function valuesDraftOf(result: AgentsMdImport, source: string): string | null;
+/**
+ * Render the draft policy YAML. Deterministic: no clock, no cwd, no
+ * randomness — the only inputs are the import result and the source label, so
+ * the same file always produces the same bytes.
+ *
+ * With `values` omitted (or from a source that declared no values headings) the
+ * output is bare YAML with no fence, a valid policy under
+ * `schema/policy.schema.json` that loads through `loadPolicy` once wrapped in a
+ * ` ```yaml approval-policy ` fence.
+ *
+ * With a values draft the shape changes, and it has to. A values fence appended
+ * to bare YAML could not be pasted into a policy fence, because the values
+ * block's own closing fence would close the policy block and leave a file that
+ * loads as neither. So a two-block draft is emitted already fenced: the policy
+ * inside its ` ```yaml approval-policy ` fence, then the values fence after it,
+ * which is the shape `APPROVAL.md` itself has and which the policy loader and
+ * the values reader each read straight off disk.
+ */
+export declare function renderDraftPolicy(result: AgentsMdImport, source: string, values?: ValuesDraft | null): string;
+/**
+ * The draft wrapped in its ` ```yaml approval-policy ` fence, for stdout, with
+ * the values fence printed after it when the source declared values headings.
+ */
+export declare function renderFencedDraft(result: AgentsMdImport, source: string, values?: ValuesDraft | null): string;