@nanonets/graft 0.23.1 → 0.24.1

package/dist/notes/notes.d.ts

@@ -1,8 +1,14 @@
+import type { NoteHit } from "./find-notes.js";
+import { type LearningFields } from "./learning-fields.js";
+export { findNotes, type NoteHit } from "./find-notes.js";
+export { mentionedFiles, noteTargets, type NoteTarget } from "./targets.js";
+export { commitLines, namesLabel, PR_SPEEDUP, setupCommitLine, TOKEN_CREDIT_FLOOR, tokensLabel, tokensWorthSaying } from "./credit.js";
 export interface NoteCost {
     minutes?: number;
     tokens?: number;
 }
-export interface Note {
+/** A learning. Its id, kind, scope, status and the rest are in `LearningFields`. */
+export interface Note extends LearningFields {
     /** Where the note is: an absolute path on this machine. */
     path: string;
     title: string;
@@ -16,12 +22,14 @@ export interface Note {
     body: string;
     /** Written by someone other than whoever is asking. */
     teammate?: boolean;
-    /** `repo`: in the repo's `.trail/learnings/`, for everyone. `personal`: in ~/.trail, this machine only. */
-    scope?: "repo" | "personal";
     /** A rule or preference for every session here, not knowledge about one
      * task: what the user kept having to tell Claude. The session-start hook
      * lists these up front, since no single task would bring them up. */
     standing?: boolean;
+    /** The file name of an earlier learning this one takes over from. The old
+     * file stays, as the record of what that session knew, but `listNotes`
+     * reads this one instead. */
+    replaces?: string;
     /** Found on a teammate's pushed branch (`origin/kumar/jitter`) rather than in
      * this checkout. `path` is then `<ref>:.trail/learnings/<name>`, readable
      * with `git show`, and the whole body travels with the note. */
@@ -44,7 +52,11 @@ export declare const SECTIONS: readonly [{
     readonly label: "watch out";
 }];
 export declare function renderNote(n: Omit<Note, "path">): string;
-/** A note file, or null when it isn't one (no title in its frontmatter). */
+/**
+ * A note file, or null when it isn't one (no title in its frontmatter), or
+ * when its front matter is refused (anchors, aliases, a list for a title) or
+ * isn't valid YAML, which says so once on stderr.
+ */
 export declare function parseNote(text: string, path: string): Note | null;
 /** The file name a note is known by, wherever it sits: one learning on a branch and in the tree is one learning. */
 export declare function noteName(n: Note): string;
@@ -75,73 +87,32 @@ export interface WriteNoteInput {
     cost?: NoteCost;
     touches?: string[];
     standing?: boolean;
+    /** The fields a new learning may be given; its id, status and scope come from where it is written. */
+    kind?: LearningFields["kind"];
+    replaces?: string;
+    src?: LearningFields["src"];
+    evidence?: string;
+    /** Personal only: defaults to this repo. */
+    applies?: string;
 }
 /**
  * Write a new learning for the repo `dir` is in, and return it: into the
  * repo's `.trail/learnings/` (made if needed), or with `scope: "personal"`,
  * or outside git, into ~/.trail. Never overwrites: a second one with the same
- * name on the same day gets `-2`, `-3`.
+ * name on the same day gets `-2`, `-3`. Its id is 8 hex digits from the file
+ * name it gets (`newLearningId`), written into the file.
  */
 export declare function writeNote(dir: string, input: WriteNoteInput, scope?: LearningScope): Note;
 /**
  * The standing learnings for `dir`: the team's in the checkout and the
  * person's own, never ones on a teammate's unmerged branch, which nobody has
- * reviewed yet.
+ * reviewed yet, and only live ones (nothing retired or replaced).
  */
 export declare function standingLearnings(dir: string): Note[];
 /** Where a learning is, as the agent and the person read it: `.trail/learnings/x.md`, `~/.trail/…`, or `origin/b:.trail/…`. */
 export declare function notePlace(n: Note): string;
-export interface NoteTarget {
-    /** A folder in the repo the note goes to. */
-    dir: string;
-    /** What the session touched there, relative to the top of that checkout. */
-    touches: string[];
-    /** What it only read there, same form; set when the session said what it read. */
-    read?: string[];
-}
-/**
- * Which repos a session's note belongs in, and what it touched in each.
- *
- * The repo the note was saved from gets the files it has uncommitted or
- * committed since `since`. Every other repo the session edited (`edited`:
- * absolute paths, from the agent's transcript) gets the note too, with its
- * own files, so a session that changed a backend and the library it calls
- * leaves a note in both. Saved from a folder that holds several repos, the
- * note goes to each repo the session changed, or stays with the folder when
- * it changed none. Two worktrees of one repo are one repo.
- *
- * `session.read`, when the transcript was found: the files the session opened.
- * Then the transcript says what was touched, and the working tree's other
- * uncommitted files, there before the session began, are left out.
- */
-export declare function noteTargets(dir: string, edited?: string[], since?: number, session?: {
-    read: string[];
-}): NoteTarget[];
-/**
- * Files of the checkout at `dir` that a note's text names by path. A session
- * that only read code edits nothing, so without these its note would touch no
- * file, and nothing that looks a note up by file (`trail check`, the ranked
- * search) would ever find it.
- */
-export declare function mentionedFiles(dir: string, body: string): string[];
-export interface NoteHit {
-    note: Note;
-    score: number;
-    /** Files the note touches that this query's results also point into. */
-    shared: string[];
-}
-/**
- * The notes worth showing next to a query's results: ones whose title or body
- * share the query's words, or that touch a file the results point into. At
- * most `limit`, best first. A note has to clear a bar — two of the query's
- * words, or one in its title, or a shared file — so an unrelated note never
- * rides along just because it exists.
- */
-export declare function findNotes(notes: Note[], query: string, files?: string[], limit?: number): NoteHit[];
 /** `2026-10-07` → `Oct 7`; anything else as it came. */
 export declare function shortDate(date: string): string;
-/** `~9.6k tokens`, `~600 tokens`. */
-export declare function tokensLabel(n: number): string;
 /** `took 12 min and ~9.6k tokens to work out`, or null when the note has no cost. */
 export declare function costLabel(cost?: NoteCost): string | null;
 /** What reading a note costs an agent, in tokens: its text at ~4 characters a token. */
@@ -151,7 +122,7 @@ export declare function readingTokens(n: Note): number;
  * it costs. 0 when it carries no token cost, or reading it costs as much.
  */
 export declare function savedByNote(n: Note): number;
-/** `Anirudh's learning`, `a learning`, `Kumar's learning on kumar/jitter`. */
+/** `Maya's learning`, `a learning`, `Kumar's learning on kumar/jitter`. */
 export declare function whoseLearning(n: Note): string;
 /**
  * The block `ask` prints above its results: whose learning each is, when,
@@ -159,39 +130,12 @@ export declare function whoseLearning(n: Note): string;
  * where to read the rest. A learning on a teammate's unmerged branch says so,
  * with the `git show` that prints it, since there's no file here to open. An agent
  * relays the cost when it says what the turn saved, which is how the saving
- * becomes countable.
+ * becomes countable. Every field is flattened to one line: a learning's text
+ * comes from whoever wrote it, and a line of its own could pass for trail's.
  */
 export declare function formatNoteHits(hits: NoteHit[]): string[];
 /** The line an agent closes its reply with after saving a learning just for the user. */
 export declare const PERSONAL_SAVED_LINE = "\uD83D\uDCDD Saved just for you \u00B7 stays on this machine, out of the repo";
-/** `Anay`, `Anay and Rushil`, `Anay, Rushil and 3 others`. */
-export declare function namesLabel(names: string[]): string;
-/** What starting from a teammate's learning is worth when its tokens are too few to say: time to a PR. */
-export declare const PR_SPEEDUP = "3x faster";
-/**
- * Below this many tokens, what a learning saves is too small a number to
- * impress, so trail credits it as a faster PR instead.
- */
-export declare const TOKEN_CREDIT_FLOOR = 80000;
-/** Whether a token count is big enough to be the credit. */
-export declare function tokensWorthSaying(tokens: number | undefined): boolean;
-/**
- * The lines that close a reply after a team learning is saved, one for each
- * way the turn can end, since only the agent knows whether it committed the
- * learning by then. Uncommitted, it makes the case for committing: who else
- * works on the same files, and the head start their agents would get, which
- * is what the learning took to work out, or a faster PR when that's small.
- */
-export declare function commitLines(note: Pick<Note, "cost">, teammates: string[], where?: "files" | "repo"): {
-    committed: string;
-    uncommitted: string;
-};
-/**
- * The line asking for trail's shared setup to be committed, once: `.trail/`
- * and the SessionStart entry in `.claude/settings.json` are what let a
- * teammate's Claude read the learnings before they install anything.
- */
-export declare function setupCommitLine(teammates: string[]): string;
 /**
  * What starting from these learnings is worth, for the agent's closing line:
  * the tokens they saved, less what reading them costs, when that's worth

package/dist/notes/notes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/notes/notes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/notes/notes.ts"],"names":[],"mappings":"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"}