@mesh-tech/mesh-cli 0.1.1 → 0.12.0

package/dist/src/docs/assemble.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Assembly: turn the discovered doc roots into a plain content tree plus a
+ * navigation manifest, ready for a docs renderer (Zudoku today) to build.
+ *
+ * The seam of the whole design is here: assembly's output is a directory of
+ * markdown files, a generated `zudoku.config.ts`, and a publish manifest.
+ * Nothing downstream knows about Mesh; nothing upstream knows about Zudoku.
+ *
+ * What assembly does, per page:
+ *   - derives the title (front-matter `title:` → first `#` heading → filename)
+ *     and writes it into the assembled front-matter, so nav labels and page
+ *     titles can never drift apart
+ *   - rewrites links: a relative link between two published files is correct
+ *     *on disk* but meaningless at a route, so published targets become
+ *     routes, unpublished-but-real files become repo blob links (reported as
+ *     `external`), and links that resolve to nothing are reported `broken`
+ *   - footers the page with the exact repo file it came from, so a reader who
+ *     spots a mistake knows where to fix it
+ *
+ * It also emits the publish manifest — every source path that made it into
+ * the site — which the CI gate uploads and diffs so growing the public
+ * surface is a thing a reviewer sees.
+ */
+import type { DiscoveredPage, Discovery } from "./discover.js";
+export type LinkIssueKind = "broken" | "external";
+export interface LinkIssue {
+    kind: LinkIssueKind;
+    /** Route of the page whose markdown contains the link. */
+    page: string;
+    /** The href exactly as written in the source markdown. */
+    href: string;
+}
+export interface AssembledPage {
+    /** Repo-relative source path. */
+    source: string;
+    /** Absolute site route, e.g. "/building-apps/primitives/service" or "/". */
+    route: string;
+    /** Route without the leading slash — also the assembled file's stem path. */
+    filePath: string;
+    title: string;
+    sectionTitle: string;
+    sectionOrder: number;
+    sectionSlug: string;
+    /** Position within its directory: front-matter `order:` → undefined (filename sort). */
+    order?: number;
+}
+export interface PublishManifest {
+    version: 1;
+    count: number;
+    /** Every repo-relative source path that made it into the site, sorted. */
+    sources: string[];
+}
+export interface AssembleResult {
+    outDir: string;
+    pages: AssembledPage[];
+    navigation: unknown[];
+    brokenLinks: LinkIssue[];
+    externalLinks: LinkIssue[];
+    publishManifest: PublishManifest;
+    /** Fail-closed assertion data: assembled output paths containing a reserved segment. */
+    reservedViolations: string[];
+}
+interface FrontMatter {
+    data: Record<string, unknown>;
+    body: string;
+    hasFrontMatter: boolean;
+}
+/**
+ * Split a markdown document into front-matter and body. Only a `---` fence on
+ * the very first line counts — a horizontal rule later in the prose is not
+ * front-matter. A YAML parse failure is not fatal: the document is treated as
+ * having no front-matter (the heading/filename title fallbacks still apply),
+ * because one bad page must not take the whole site down at assemble time.
+ */
+export declare function splitFrontMatter(markdown: string): FrontMatter;
+/**
+ * The title derivation order, fixed by the design: front-matter `title:` →
+ * first `#` heading → filename. `sidebar_label` wins for the nav when present
+ * (Zudoku honours it), but the document still gets its real title.
+ */
+export declare function deriveTitle(frontMatter: Record<string, unknown>, body: string, source: string): string;
+export interface LinkResolution {
+    href: string;
+    issue?: LinkIssue;
+}
+/**
+ * Remove HTML comments (`<!-- … -->`, single- or multi-line) from a page body.
+ * They are invisible in any rendered output by definition — the source file
+ * keeps them — and multi-line comments currently crash Zudoku's MDX plugin
+ * (`chunks[startIndex].slice is not a function`), which turns one authored
+ * comment into a failed site build. Fenced code blocks are left alone: a doc
+ * *teaching* HTML comments shows them as code, and that code must survive.
+ */
+export declare function stripHtmlComments(body: string): string;
+/**
+ * Resolve one link, exactly the #3503 semantics with routes instead of slugs:
+ *
+ *   - anchors, absolute URLs, mailto: → untouched
+ *   - an `ignoreLinkPrefixes` match → untouched (declared deliberately
+ *     unresolvable — the app-kit README's `node_modules/…` guidance exists in
+ *     a tenant's install, never in this repo)
+ *   - a file the portal publishes → that page's route
+ *   - a directory whose index/README the portal publishes → that route
+ *   - a real repo file the portal does not publish → a repo blob link
+ *     (reported `external`)
+ *   - nothing → reported `broken`
+ *   - a site-rooted path (`/guides/x`) → validated against the route set, so a
+ *     typo'd route fails the gate instead of shipping as a 404
+ */
+export declare function resolveLink(args: {
+    href: string;
+    pageRoute: string;
+    sourceDir: string;
+    sourceIndex: Map<string, AssembledPage>;
+    routes: Set<string>;
+    ignoreLinkPrefixes: string[];
+    /** Exists-on-disk probe (file OR directory); returns "file" | "dir" | null. */
+    pathKind: (repoRelPath: string) => "file" | "dir" | null;
+    repoUrl: string;
+}): LinkResolution;
+/** Rewrite every link in a page body, collecting issues. */
+export declare function rewriteLinks(args: {
+    body: string;
+    page: AssembledPage;
+    sourceIndex: Map<string, AssembledPage>;
+    routes: Set<string>;
+    ignoreLinkPrefixes: string[];
+    pathKind: (repoRelPath: string) => "file" | "dir" | null;
+    repoUrl: string;
+}): {
+    body: string;
+    issues: LinkIssue[];
+};
+export interface AssembleOptions {
+    repoRoot: string;
+    discovery: Discovery;
+    /** Directory the assembled markdown tree is written to. */
+    outDir: string;
+    repoUrl?: string;
+    ignoreLinkPrefixes?: string[];
+    /**
+     * Version string stamped into the footer + version.json — the fixed
+     * lockstep group's version post-`changeset version`. Undefined outside a
+     * release build.
+     */
+    meshBaseline?: string;
+    /** Short commit the build is from. */
+    commit?: string;
+}
+/** A page's full route: section slug + route path. "/" for the site home. */
+export declare function pageRoute(page: DiscoveredPage): string;
+/** The assembled file path (no leading slash, with extension). */
+export declare function pageFilePath(route: string): string;
+/**
+ * Assemble the discovered pages into `outDir`. Pure function of the repo tree
+ * — the same inputs always produce the same tree, manifest, and navigation.
+ */
+export declare function assemblePortal(options: AssembleOptions): AssembleResult;
+/**
+ * Build the Zudoku navigation array from the assembled pages.
+ *
+ * Shape: one root category ("Documentation", clicking it lands on the home
+ * page) whose items are one non-collapsible category per doc root — the
+ * sidebar's section headers — each holding the section's tree: pages as doc
+ * items, directories as nested categories. A directory with an index page
+ * becomes a clickable category (its link); the section's own index page
+ * becomes the section category's link. Order is front-matter `order:` first,
+ * then filename — never declared anywhere but the files themselves.
+ */
+export declare function buildNavigation(pages: AssembledPage[]): unknown[];
+/**
+ * Render the generated `zudoku.config.ts`. It is regenerated on every
+ * assemble and gitignored — the navigation manifest is derived state, and
+ * committed derived state is how the old manifest rotted.
+ */
+export declare function renderZudokuConfig(args: {
+    navigation: unknown[];
+    title: string;
+    description: string;
+    baseline?: string | undefined;
+    commit?: string | undefined;
+}): string;
+/** version.json — the version-parity contract the parity monitor asserts. */
+export declare function renderVersionJson(args: {
+    baseline?: string | undefined;
+    commit: string;
+    builtAt: string;
+}): string;
+/** Best-effort short commit of the repo being assembled. */
+export declare function currentCommit(repoRoot: string): string;
+/** The fixed lockstep group's version, read from app-kit's package.json. */
+export declare function currentBaseline(repoRoot: string): string | undefined;
+export interface PublishSetDiff {
+    added: string[];
+    removed: string[];
+}
+/**
+ * Compute the publish set of another git ref WITHOUT checking it out — the
+ * docs.json files and tree listing are read via `git show`/`git ls-tree`, and
+ * the same discovery rules (reserved segments, README exclusion, include[])
+ * are applied to that listing. Lets a PR diff its publish set against its
+ * merge base in a CI job that has no second worktree and no installed deps
+ * for the base.
+ *
+ * APPROXIMATION, base side only: this reimplementation skips schema
+ * validation (an invalid docs.json publishes nothing in real discovery but
+ * is walked here), nested-root rejection, and route-collision detection, so
+ * it can OVER-report the base's publish set (a spurious "removed" row in the
+ * summary) — never under-report the head's. The head side is always real
+ * discovery; the gate's assertions never read this function.
+ */
+export declare function publishSetAtRef(repoRoot: string, ref: string): string[];
+export declare function diffPublishSets(base: string[], head: string[]): PublishSetDiff;
+/** Render the publish-set diff as a GitHub job-summary markdown block. */
+export declare function renderPublishSetSummary(manifest: PublishManifest, diff: PublishSetDiff | null): string;
+export {};
+//# sourceMappingURL=assemble.d.ts.map

package/dist/src/docs/assemble.d.ts.map

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