@dmthepm/commune 0.1.0

package/lib/lib/graph.d.ts

@@ -0,0 +1,354 @@
+/**
+ * The content graph core.
+ *
+ * Every mechanism that needs to know "what content exists and where does it
+ * live" reads from here: the remark WikiLinks plugin, the backlinks Astro
+ * integration, and the search-index check. Before this module those three
+ * carried hand-synced copies of the same directory scan, the same visibility
+ * rules, and three subtly different opinions about trailing slashes.
+ *
+ * The rules this module owns:
+ *   - which collections participate (notes, research, pages)
+ *   - visibility (notes opt in with `visibility: public`; research and pages
+ *     are always public)
+ *   - canonical URLs, always with a trailing slash, matching Astro's
+ *     directory build format
+ *   - the title/alias lookup used to resolve `[[WikiLinks]]`
+ *   - which link forms count as an edge, and how each one resolves
+ */
+export type CollectionName = 'notes' | 'research' | 'pages';
+/** Where each collection's markdown lives, relative to the project root. */
+export declare const CONTENT_DIRS: Record<CollectionName, string>;
+/** Collection scan order. Stable so derived artifacts are deterministic. */
+export declare const COLLECTIONS: CollectionName[];
+/** One piece of public content, as the graph sees it. */
+export interface ContentEntry {
+    /** Collection-relative slug, e.g. `evergreen-notes`. Not unique across collections. */
+    slug: string;
+    /** Canonical site path with a trailing slash, e.g. `/notes/evergreen-notes/`. Unique. */
+    urlPath: string;
+    title: string;
+    collection: CollectionName;
+    aliases: string[];
+    tags: string[];
+    status: string;
+    summary?: string;
+    updated?: string;
+    /** Markdown body with frontmatter stripped. */
+    body: string;
+    /** Parsed frontmatter. Kept because links can live in it. */
+    frontmatter: Record<string, unknown>;
+    /** Source file path, relative to the project root. */
+    file: string;
+}
+/** What a resolved `[[WikiLink]]` points at. */
+export interface LinkTarget {
+    slug: string;
+    collection: CollectionName;
+    urlPath: string;
+}
+/**
+ * Convert a content file path to its collection-relative slug and canonical URL.
+ *
+ * Files are named for their titles, so that `[[Evergreen Notes]]` resolves in
+ * Obsidian (which matches on filename) and in Astro (which matches on title)
+ * without a piped alias. The URL is therefore *derived* from the filename, not
+ * equal to it, using the same `github-slugger` call Astro's own content layer
+ * uses — so the graph and Astro's `entry.slug` can never disagree.
+ *
+ * Two escape hatches, in priority order:
+ *   - `slug` frontmatter pins the URL when a rename would otherwise move it.
+ *     Astro treats this key as reserved and strips it before Zod validation, so
+ *     it must not appear in any collection schema.
+ *   - `pages` declare a whole `url`, since they render at arbitrary routes.
+ */
+export declare function toUrlPath(file: string, collection: CollectionName, data?: Record<string, unknown>): {
+    slug: string;
+    urlPath: string;
+};
+/**
+ * Convert a canonical URL path to the *file* path of its markdown twin.
+ *
+ * Every note is served twice at one URL: `/notes/cake/` renders the page,
+ * `/notes/cake.md` returns the source file. The mapping is pure string work —
+ * drop the trailing slash, append `.md` — and it lives here rather than in the
+ * build writer so the page templates cannot drift from the files that writer
+ * actually emits. The home page (`/`) has no name to hang the suffix on, so it
+ * gets `index.md`.
+ *
+ * The result is relative, with no leading slash: the caller joins it onto its
+ * output directory. For the URL a rendered page should link to, use
+ * `toMarkdownHref`. Traversal segments are rejected rather than normalized,
+ * since a `url` frontmatter is author-controlled and a `..` in it would
+ * otherwise let a build write outside its output directory.
+ */
+export declare function toMarkdownPath(urlPath: string): string;
+/**
+ * The site-absolute URL of an entry's markdown twin — what a rendered page links to.
+ *
+ * Derived from `toMarkdownPath` rather than computed alongside it, so a page's
+ * "view as markdown" link and the file the build writes can only ever be the
+ * same string with a leading slash.
+ */
+export declare function toMarkdownHref(urlPath: string): string;
+/** Coerce a frontmatter date to `yyyy-mm-dd`, so build output has no timestamp drift. */
+export declare function normalizeDate(value: unknown): string | undefined;
+/** Where to read content from. */
+export interface GraphOptions {
+    /**
+     * The project root: the directory that *contains* `src/content`, not
+     * `src/content` itself.
+     *
+     * Every path the graph exposes is derived from this directory — `file` is
+     * relative to it, and `toUrlPath` strips `CONTENT_DIRS[collection]` off the
+     * front of `file` to get a slug. Point it one level too deep and every slug
+     * silently changes. Defaults to `process.cwd()`.
+     */
+    root?: string;
+}
+/**
+ * Read every public content entry, in a stable order.
+ *
+ * Deliberately uncached: the backlinks integration runs this on each build hook
+ * and the dev server must see content edits without a restart.
+ *
+ * The root is a parameter rather than a `process.chdir`, so one process can
+ * read several vaults — which is what the CLI does when it is pointed at
+ * another wiki — without the cwd becoming shared mutable state.
+ */
+export declare function loadContentEntries(options?: GraphOptions): Promise<ContentEntry[]>;
+/**
+ * Build the `[[WikiLink]]` resolution table: lowercased title or alias → target.
+ *
+ * Titles win over aliases, and within each pass later entries win — which only
+ * matters when two pieces of content claim the same name, and is a content bug
+ * either way.
+ */
+export declare function buildLinkLookup(entries: ContentEntry[]): Map<string, LinkTarget>;
+/**
+ * Build the url resolution table: canonical `urlPath` → target.
+ *
+ * Separate from the title/alias lookup on purpose. A path and a title are
+ * different namespaces, and mixing them is what let `/notes/atomic-notes`
+ * resolve through an alias rather than through the route it actually names.
+ */
+export declare function buildUrlLookup(entries: ContentEntry[]): Map<string, LinkTarget>;
+/**
+ * Build the filename resolution table: lowercased basename → target.
+ *
+ * Not a resolution table — nothing resolves through it. It exists so `check`
+ * can notice when a name means two different things depending on which table
+ * you ask: `[[Index]]` resolves by *title*, but `[index](./Index.md)` names a
+ * *file*, and in a vault where those disagree one of the two is silently wrong.
+ * Obsidian resolves by filename and Astro by title, so this is the seam where
+ * the two tools stop agreeing about what a link points at.
+ */
+export declare function buildBasenameLookup(entries: ContentEntry[]): Map<string, LinkTarget[]>;
+/**
+ * Resolve one extracted edge, using the table its kind belongs to.
+ *
+ * Deliberately does nothing clever: no basename fallback, no source-relative
+ * disambiguation, no collision policy. Those are resolution questions, tracked
+ * on #18; this is extraction's other half and nothing more.
+ */
+export declare function resolveLink(link: ExtractedLink, byName: Map<string, LinkTarget>, byUrl: Map<string, LinkTarget>): LinkTarget | undefined;
+/**
+ * The link lookup for one project root, built once and reused.
+ *
+ * The remark plugin runs per markdown file, so rescanning the content tree on
+ * every transform would make builds quadratic. Call `resetGraphCache()` if a
+ * caller needs to see content written during the same process.
+ */
+export declare function getLinkLookup(options?: GraphOptions): Promise<Map<string, LinkTarget>>;
+export declare function resetGraphCache(): void;
+/**
+ * Blank out fenced blocks and inline code, preserving offsets.
+ *
+ * A `[[WikiLink]]` written inside backticks is documentation *about* the
+ * syntax, not a link. The remark plugin gets this right for free because it
+ * only visits `text` nodes and never `inlineCode` — anything scanning raw
+ * markdown has to strip code itself or it reports phantom broken links.
+ */
+export declare function stripCode(content: string): string;
+/**
+ * How a link target should be resolved.
+ *
+ * `name` is title-shaped: the raw text of a `[[WikiLink]]`, or the basename of
+ * a relative file link, resolved against the title/alias lookup.
+ * `url` is path-shaped: an absolute site path, resolved against `urlPath`.
+ *
+ * The two cannot be collapsed into one string. A bare `atomic-notes` is not a
+ * title and matching it against one only works by coincidence; `/notes/atomic-notes/`
+ * is not a title either and must never be looked up as one.
+ */
+export type LinkKind = 'name' | 'url';
+/** One outbound edge, with enough information to resolve it. */
+export interface ExtractedLink {
+    kind: LinkKind;
+    target: string;
+}
+/**
+ * Extract every outbound link target from a markdown body and its frontmatter.
+ *
+ * Returns the edges Obsidian's `resolvedLinks` would record: wikilinks, embeds,
+ * internal markdown links, and `frontmatterLinks`. Code is excluded.
+ *
+ * Frontmatter is passed separately because it is already parsed by the time it
+ * reaches here — `loadContentEntries()` splits it off with gray-matter, so the
+ * body alone can never contain it.
+ */
+export declare function extractLinks(content: string, frontmatter?: Record<string, unknown>): ExtractedLink[];
+/**
+ * The shape of the star calculation strategy.
+ *
+ * Declared as an interface rather than inferred from the value, because the
+ * value picks one member of each union and `calculateStars` switches over all
+ * of them. With `as const` on the fields, TypeScript narrows `strategy` to the
+ * literal `'top-percent'` and every other arm of that switch becomes an error
+ * — the config would be untunable without editing the code that reads it,
+ * which is the opposite of what a config is for.
+ */
+export interface StarConfig {
+    strategy: 'top-percent' | 'top-absolute' | 'threshold';
+    /** For 'top-percent': what percentage gets stars. */
+    topPercent: number;
+    /** For 'top-absolute': how many notes get stars. */
+    topAbsolute: number;
+    /** For 'threshold': minimum backlinks to get a star. */
+    threshold: number;
+    /** Below this many notes, nobody is starred. */
+    minNotesForStars: number;
+    rankBy: 'backlinks' | 'revisions' | 'cross-theme' | 'weighted';
+    /** For 'weighted' ranking (future). */
+    weights: {
+        backlinks: number;
+        revisions: number;
+        crossTheme: number;
+    };
+}
+/**
+ * Star calculation strategy.
+ *
+ * Lives in the core rather than the Astro integration because `isStarred` is a
+ * field of the public artifact, and the CLI has to be able to produce the same
+ * artifact without loading Astro.
+ */
+export declare const STAR_CONFIG: StarConfig;
+/**
+ * One node of the public graph, and one entry of `backlinks.json`.
+ *
+ * The property order here is a serialization contract: `backlinks.json` is
+ * committed, and a reordered object is a diff on every build.
+ */
+export interface NoteMetadata {
+    /** Canonical URL path. The graph is keyed by URL, so this is the identity. */
+    slug: string;
+    title: string;
+    collection: CollectionName;
+    aliases: string[];
+    outbound: string[];
+    inbound: string[];
+    tags: string[];
+    status: string;
+    summary?: string;
+    updated?: string;
+    isStarred?: boolean;
+}
+/** Which rules the graph and `check` can report. */
+export type DiagnosticRule = 'broken-link' | 'ambiguous-target' | 'duplicate-name' | 'noncanonical-title';
+/**
+ * One finding, as data.
+ *
+ * The Astro integration used to print broken links inline, which meant the only
+ * way to get at them was to scrape build logs. Findings are values now, so the
+ * integration, `check` and the search-index gate can each render the same set
+ * their own way.
+ */
+export interface Diagnostic {
+    rule: DiagnosticRule;
+    severity: 'error' | 'warning';
+    /** Source file, relative to the project root. */
+    file: string;
+    /** Not tracked yet: `extractLinks` records no offsets. Added when #24 needs them. */
+    line?: number;
+    message: string;
+    /** The link text or name involved. */
+    target?: string;
+    /** Canonical URL of the entry the finding is in. Carried so build output can name the route. */
+    urlPath?: string;
+    /** How the offending link was spelled, which decides `[[name]]` vs `(url)` rendering. */
+    kind?: LinkKind;
+    /** urlPaths in contention, for `ambiguous-target` and `duplicate-name`. */
+    candidates?: string[];
+    /** The spelling a `noncanonical-title` finding should have used. */
+    canonical?: string;
+}
+/** The resolved content graph. */
+export interface Graph {
+    /** Keyed by urlPath; insertion order is entry order. */
+    nodes: Record<string, NoteMetadata>;
+    diagnostics: Diagnostic[];
+    totalBacklinks: number;
+}
+/**
+ * Calculate which notes get stars based on STAR_CONFIG.
+ * Returns a Set of slugs that should be starred.
+ */
+export declare function calculateStars(notes: Map<string, NoteMetadata>): Set<string>;
+/**
+ * Build the resolved graph from loaded entries.
+ *
+ * Pure: no filesystem, no logging, no Astro. Everything a caller might want to
+ * print comes back in `diagnostics`, so the same construction serves the build
+ * (which warns), `check` (which reports) and `related` (which does neither).
+ */
+export declare function buildGraph(entries: ContentEntry[]): Graph;
+/**
+ * Render a diagnostic as the build has always rendered it.
+ *
+ * `public/backlinks.json` is not the only committed contract — build output is
+ * read by humans and diffed by reviewers, so the warning line is kept exactly
+ * as it was when the integration formatted it itself.
+ */
+export declare function formatDiagnostic(diagnostic: Diagnostic): string;
+/**
+ * The public artifact, exactly as `public/backlinks.json` stores it.
+ *
+ * Separate from `Graph` because the file is a runtime contract with four
+ * client-side readers: the graph can grow fields, the file cannot.
+ */
+export declare function toBacklinksJson(graph: Graph): Record<string, NoteMetadata>;
+/**
+ * Names claimed by more than one entry.
+ *
+ * Two triggers, because a name lives in two namespaces: a title or alias that
+ * two entries both answer to, and a filename that two entries share. Neither
+ * is an error the graph can resolve — `buildLinkLookup` keeps last-wins, which
+ * is what it has always done — but both mean a `[[WikiLink]]` reaches somewhere
+ * its author did not choose, and silently.
+ *
+ * Reported against the *first* claimant, because that is the entry the
+ * collision makes unreachable.
+ */
+export declare function findDuplicateNames(entries: ContentEntry[]): Diagnostic[];
+/**
+ * WikiLinks that resolve but do not name their target exactly.
+ *
+ * The rule this implements used to live in the build gate script, with its own
+ * lookup table and its own regex — a second copy of a rule the graph core
+ * already had the ingredients for, which is the bug class #3 was opened to
+ * kill. One implementation now, two callers: `check` reports it and
+ * `commune gate` fails on it.
+ *
+ * Worth checking precisely because it is invisible: a piped link or a
+ * near-miss title still renders, and the vault quietly decouples from the site.
+ */
+export declare function findNoncanonicalTitles(entries: ContentEntry[]): Diagnostic[];
+/**
+ * Every finding `check` reports.
+ *
+ * The graph's own diagnostics come first and in entry order, so the list reads
+ * the same way the build log does, then the two whole-corpus rules that need
+ * every entry in hand before they can fire.
+ */
+export declare function checkEntries(entries: ContentEntry[], graph: Graph): Diagnostic[];