@ingcreators/annot-product-docs 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,105 @@
+# @ingcreators/annot-product-docs
+
+## 0.2.0
+
+### Minor Changes
+
+- 2e92c97: First publish of the living-product-docs package family. Phases
+  1-5 + 7 of `docs/plans/living-product-docs.md` landed across
+  PRs 876-899; this entry flips the three packages from
+  `private: true` to publishable and stamps `0.1.0`.
+
+  ### `@ingcreators/annot-product-docs`
+  - MDX parser (`parseMdx` / `parseMdxFile`) — Remark / unified
+    pipeline that walks `.mdx` files with `annot:` frontmatter
+    and extracts `<Screen>` / `<Overlay>` / `<Transition>` /
+    `<HistoryEntry>` / `<ScreenList>` JSX components.
+  - Match resolver (`parseSnapshot` / `resolveMatch` /
+    `resolveOverlays`) for the Playwright `aria-snapshot`
+    YAML, honouring `match.under` disambiguation and emitting
+    `not-found` / `ambiguous` / `renamed` / `role-changed` /
+    `live-mismatch` diagnostics.
+  - `screen` fixture extending `@ingcreators/annot-playwright`
+    with `screen.capture({ id, mdxPath })` that re-syncs
+    `annot:snapshot` + `annot:attributes` MDX comment blocks
+    in place.
+  - Drift detector (`detectDrift` / `detectDriftFromYaml`) — six
+    finding kinds (added / removed / renamed / role-changed /
+    duplicated / attribute-drift) with severity buckets.
+  - `annot-docs` CLI (`init` / `sync` / `lint`) with `--json`
+    / `--ci` / `--fix` flags + a sample GitHub Actions workflow
+    emitting GitHub annotations on PR diff views.
+
+  ### `@ingcreators/annot-product-docs-astro`
+  - `productDocsIntegration()` Astro 5.x integration factory.
+  - 7 docs components: `<Screen>`, `<Overlay>`, `<Transition>`,
+    `<TransitionTable>`, `<HistoryEntry>`, `<ScreenList>`,
+    `<TransitionGraph>`. Shipped as `.astro` source under
+    `./components/*.astro` exports.
+  - Image Service (`renderAnnotatedScreen` + SHA-keyed
+    `createFileCache` / `createMemoryCache`) that composes the
+    base screenshot with overlay callouts at build time.
+
+  ### `@ingcreators/annot-product-docs-xlsx`
+  - MDX → normalised bundle extractor; per-role default layout
+    (cover / history / list / screen / reference); customer-
+    template support with `{var}` placeholder substitution
+    (including `{annot:date}` special vars + `{name:format}`
+    date formatting); Excel Named Range writers
+    (`annotImage` / `annotItemTable` / `annotHistory` /
+    `annotList` / `annotSnapshot` / `annotAttributes`).
+  - `annot-docs-xlsx render` CLI with multi-book emit + per-book
+    template config.
+
+### Patch Changes
+
+- 657a685: **Republish with `dist/` included.** The `0.1.0` tarballs of all
+  three packages shipped to npm without their `dist/` directory —
+  the `publish.yml` workflow's pre-pack `pnpm build` step had only
+  filtered four other packages, so `pnpm pack` packed the three
+  `product-docs*` packages against empty `dist/`s. The
+  `publishConfig.main` (`./dist/index.js`) consequently pointed at
+  a missing file, breaking `npm install` for every consumer.
+
+  The source fix landed in
+  [#947](https://github.com/ingcreators/annot/pull/947) with two
+  defences:
+  1. Three new `--filter` lines in the workflow's build step so
+     all seven publishable packages get built before pack.
+  2. A per-package `prepack` script (`pnpm run build`) so even a
+     misconfigured workflow (or a manual `pnpm pack` / `pnpm
+publish`) refreshes `dist/` before packing.
+
+  No source-code changes in any of the three packages — only the
+  packaging is fixed. This patch publish exists solely to deliver
+  working tarballs to the registry; the public API surface is
+  byte-identical to `0.1.0`.
+
+  Verified locally:
+
+  ```
+  $ pnpm --filter @ingcreators/annot-product-docs pack --dry-run
+  Tarball Contents
+    bin/annot-docs.mjs
+    dist/cli.d.ts
+    dist/config.d.ts
+    dist/drift.d.ts
+    dist/fixture.d.ts
+    dist/index.d.ts
+    dist/index.js
+    dist/mdx.d.ts
+    dist/resolver.d.ts
+    dist/types-config.d.ts
+    dist/types.d.ts
+    LICENSE
+    package.json
+    README.md
+  ```
+
+  Before the fix the same command produced 4 files (LICENSE +
+  README + package.json + bin/annot-docs.mjs), no compiled code.
+
+- Updated dependencies [806badc]
+- Updated dependencies [df1a429]
+  - @ingcreators/annot-annotator@0.5.0
+  - @ingcreators/annot-playwright@0.3.1

package/README.md

@@ -4,11 +4,11 @@
 [![license](https://img.shields.io/npm/l/@ingcreators/annot-product-docs.svg)](https://github.com/ingcreators/annot/blob/main/LICENSE)
 
 Living product docs core. Turn a Playwright tour suite into
-always-fresh user manuals + Japanese 画面設計書, with drift
-between MDX and live UI caught as a CI lint step.
+always-fresh user manuals + Excel screen specifications, with
+drift between MDX and live UI caught as a CI lint step.
 
 Phase 1 of
-[`docs/plans/living-product-docs.md`](https://github.com/ingcreators/annot/blob/main/docs/plans/living-product-docs.md).
+[`docs/plans/_done/living-product-docs.md`](https://github.com/ingcreators/annot/blob/main/docs/plans/_done/living-product-docs.md).
 
 ## Install
 
@@ -99,7 +99,7 @@ annot-docs lint --fix                    # auto-refresh stored blocks for files
 
 The companion adapters consume the MDXs:
 - [`@ingcreators/annot-product-docs-astro`](../product-docs-astro) renders an Astro docs site.
-- [`@ingcreators/annot-product-docs-xlsx`](../product-docs-xlsx) emits Excel 画面設計書.
+- [`@ingcreators/annot-product-docs-xlsx`](../product-docs-xlsx) emits Excel screen specifications.
 
 ## Tier
 

package/dist/cli.d.ts

@@ -0,0 +1,29 @@
+import { Page } from 'playwright-core';
+export interface CliOptions {
+    cwd?: string;
+    /** Write target for diagnostic output (defaults to process.stderr). */
+    stderr?: (line: string) => void;
+    stdout?: (line: string) => void;
+    /** Override Playwright launch (used in tests). Returns an already-open `Page`. */
+    newPage?: (url: string) => Promise<{
+        page: Page;
+        close: () => Promise<void>;
+    }>;
+}
+/**
+ * `main(argv)` entrypoint. Returns the process exit code so the
+ * bin script (`bin/annot-docs.mjs`) can `process.exit(...)`. Also
+ * usable from vitest by passing custom `stdout` / `stderr` / `cwd`.
+ */
+export declare function main(argv: string[], options?: CliOptions): Promise<number>;
+/**
+ * Walk the directory tree below `root` and return every `*.mdx`
+ * absolute path. Uses `readdir({ withFileTypes: true })` for a
+ * single syscall per directory — no external glob dep.
+ */
+export declare function walkMdx(root: string): Promise<string[]>;
+/**
+ * Filter a list of MDX paths down to the ones with `annot:`
+ * frontmatter — i.e. the files the CLI should act on.
+ */
+export declare function filterAnnotMdxFiles(paths: string[]): Promise<string[]>;

package/dist/config.d.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { AnnotDocsConfig, AnnotFrontmatter } from './types-config.js';
+export declare const annotFrontmatterSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    purpose: z.ZodOptional<z.ZodString>;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    xlsx: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        book: z.ZodOptional<z.ZodString>;
+        sheet: z.ZodOptional<z.ZodString>;
+        sheets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        role: z.ZodOptional<z.ZodEnum<["cover", "history", "list", "screen", "reference"]>>;
+        order: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
+        book?: string | undefined;
+        sheet?: string | undefined;
+        sheets?: Record<string, string> | undefined;
+        order?: number | undefined;
+    }, {
+        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
+        book?: string | undefined;
+        sheet?: string | undefined;
+        sheets?: Record<string, string> | undefined;
+        order?: number | undefined;
+    }>, {
+        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
+        book?: string | undefined;
+        sheet?: string | undefined;
+        sheets?: Record<string, string> | undefined;
+        order?: number | undefined;
+    }, {
+        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
+        book?: string | undefined;
+        sheet?: string | undefined;
+        sheets?: Record<string, string> | undefined;
+        order?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    title?: string | undefined;
+    purpose?: string | undefined;
+    meta?: Record<string, unknown> | undefined;
+    xlsx?: {
+        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
+        book?: string | undefined;
+        sheet?: string | undefined;
+        sheets?: Record<string, string> | undefined;
+        order?: number | undefined;
+    } | undefined;
+}, {
+    id: string;
+    title?: string | undefined;
+    purpose?: string | undefined;
+    meta?: Record<string, unknown> | undefined;
+    xlsx?: {
+        role?: "cover" | "history" | "list" | "screen" | "reference" | undefined;
+        book?: string | undefined;
+        sheet?: string | undefined;
+        sheets?: Record<string, string> | undefined;
+        order?: number | undefined;
+    } | undefined;
+}>;
+export declare const annotDocsConfigSchema: z.ZodObject<{
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    xlsx: z.ZodOptional<z.ZodObject<{
+        defaultBook: z.ZodOptional<z.ZodString>;
+        books: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            template: z.ZodOptional<z.ZodString>;
+            templateSheets: z.ZodOptional<z.ZodObject<{
+                cover: z.ZodOptional<z.ZodString>;
+                history: z.ZodOptional<z.ZodString>;
+                list: z.ZodOptional<z.ZodString>;
+                screen: z.ZodOptional<z.ZodString>;
+                reference: z.ZodOptional<z.ZodString>;
+            }, "strict", z.ZodTypeAny, {
+                cover?: string | undefined;
+                history?: string | undefined;
+                list?: string | undefined;
+                screen?: string | undefined;
+                reference?: string | undefined;
+            }, {
+                cover?: string | undefined;
+                history?: string | undefined;
+                list?: string | undefined;
+                screen?: string | undefined;
+                reference?: string | undefined;
+            }>>;
+        }, "strict", z.ZodTypeAny, {
+            template?: string | undefined;
+            templateSheets?: {
+                cover?: string | undefined;
+                history?: string | undefined;
+                list?: string | undefined;
+                screen?: string | undefined;
+                reference?: string | undefined;
+            } | undefined;
+        }, {
+            template?: string | undefined;
+            templateSheets?: {
+                cover?: string | undefined;
+                history?: string | undefined;
+                list?: string | undefined;
+                screen?: string | undefined;
+                reference?: string | undefined;
+            } | undefined;
+        }>>>;
+    }, "strict", z.ZodTypeAny, {
+        defaultBook?: string | undefined;
+        books?: Record<string, {
+            template?: string | undefined;
+            templateSheets?: {
+                cover?: string | undefined;
+                history?: string | undefined;
+                list?: string | undefined;
+                screen?: string | undefined;
+                reference?: string | undefined;
+            } | undefined;
+        }> | undefined;
+    }, {
+        defaultBook?: string | undefined;
+        books?: Record<string, {
+            template?: string | undefined;
+            templateSheets?: {
+                cover?: string | undefined;
+                history?: string | undefined;
+                list?: string | undefined;
+                screen?: string | undefined;
+                reference?: string | undefined;
+            } | undefined;
+        }> | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    meta?: Record<string, unknown> | undefined;
+    xlsx?: {
+        defaultBook?: string | undefined;
+        books?: Record<string, {
+            template?: string | undefined;
+            templateSheets?: {
+                cover?: string | undefined;
+                history?: string | undefined;
+                list?: string | undefined;
+                screen?: string | undefined;
+                reference?: string | undefined;
+            } | undefined;
+        }> | undefined;
+    } | undefined;
+}, {
+    meta?: Record<string, unknown> | undefined;
+    xlsx?: {
+        defaultBook?: string | undefined;
+        books?: Record<string, {
+            template?: string | undefined;
+            templateSheets?: {
+                cover?: string | undefined;
+                history?: string | undefined;
+                list?: string | undefined;
+                screen?: string | undefined;
+                reference?: string | undefined;
+            } | undefined;
+        }> | undefined;
+    } | undefined;
+}>;
+/**
+ * Identity-with-validation helper.
+ *
+ * Project config files (`annot-docs.config.ts`) call this so
+ * editor tooling (TypeScript) sees the precise type. The runtime
+ * call also runs the Zod schema, so typos in the config object
+ * fail loudly at module load time rather than silently being
+ * dropped by `tsc`'s structural matching.
+ */
+export declare function defineConfig(config: AnnotDocsConfig): AnnotDocsConfig;
+export type { AnnotDocsConfig, AnnotFrontmatter, BookConfig, } from './types-config.js';
+/**
+ * Convenience guard: does this AnnotFrontmatter declare a
+ * `screen` role? Useful for filtering MDXs that have `<Screen>`
+ * blocks (and therefore drift-checkable) from cover / history /
+ * list MDXs.
+ *
+ * Defaults to `true` when `xlsx.role` is unset because plain MDXs
+ * with `<Screen>` blocks default to the `screen` role.
+ */
+export declare function isScreenRole(fm: AnnotFrontmatter): boolean;

package/dist/drift.d.ts

@@ -0,0 +1,77 @@
+import { SnapshotEntry } from './resolver.js';
+import { MatchKey, ScreenSpec } from './types.js';
+export type DriftSeverity = "error" | "warning" | "info";
+export type DriftKind = "added" | "removed" | "renamed" | "role-changed" | "duplicated" | "attribute-drift";
+export interface DriftFinding {
+    severity: DriftSeverity;
+    kind: DriftKind;
+    /** The screen id the finding pertains to. */
+    screenId: string;
+    /** Human-readable description. */
+    message: string;
+    /** The `MatchKey` from the source MDX, if relevant. */
+    match?: MatchKey;
+    /** Suggested replacement (used by `--fix` flows in Phase 4). */
+    suggestion?: {
+        role?: string;
+        name?: string;
+    };
+}
+export interface DetectDriftOptions {
+    screen: ScreenSpec;
+    /** Parsed Playwright aria-snapshot entries against the current page. */
+    liveSnapshot: SnapshotEntry[];
+    /** Optional verbatim YAML of the stored `annot:attributes` block. */
+    storedAttributesYaml?: string;
+    /** Optional verbatim YAML of the freshly-captured attributes. */
+    freshAttributesYaml?: string;
+}
+/**
+ * Compute the drift findings for one `<Screen>` block.
+ *
+ * Severity policy:
+ * - **error** stops `annot docs lint --ci` (non-zero exit). Removed
+ *   + duplicated belong here because they fail rendering.
+ * - **warning** logs but doesn't fail CI by default. Added + renamed
+ *   + role-changed belong here because they're authoring tasks (the
+ *   doc author decides whether the new element warrants an
+ *   `<Overlay>`).
+ * - **info** is silent unless `--verbose`; attribute-drift is here
+ *   because `annot docs sync` rewrites the block automatically on
+ *   the next CI run.
+ */
+export declare function detectDrift(opts: DetectDriftOptions): DriftFinding[];
+/**
+ * Convenience: parse the stored snapshot YAML + dispatch.
+ *
+ * Used by the CLI when comparing the persisted `annot:snapshot`
+ * comment block against a fresh page snapshot — e.g. for an
+ * offline `annot docs lint --offline` mode (Phase 4 polish).
+ */
+export declare function detectDriftFromYaml(args: {
+    screen: ScreenSpec;
+    liveSnapshotYaml: string;
+    storedAttributesYaml?: string;
+    freshAttributesYaml?: string;
+}): DriftFinding[];
+/**
+ * Summarise findings by severity. Used by the CLI to decide an
+ * exit code.
+ */
+export declare function summariseDrift(findings: DriftFinding[]): {
+    errors: number;
+    warnings: number;
+    infos: number;
+};
+/**
+ * A `<Screen>` is drift-checkable when it has at least one
+ * `<Overlay>`. Files without `<Screen>` blocks (cover / history /
+ * list / reference MDXs) are skipped by the lint walker.
+ */
+export declare function isLintableScreen(screen: ScreenSpec): boolean;
+/**
+ * Filter the list of `ScreenSpec`s in a parsed MDX to just the
+ * ones drift detection should touch. Helps the CLI keep the
+ * "skipped cover.mdx" path cheap.
+ */
+export declare function lintableScreens(screens: ScreenSpec[]): ScreenSpec[];

package/dist/fixture.d.ts

@@ -0,0 +1,81 @@
+import { Locator, Page } from '@playwright/test';
+import { OverlaySpec } from './types.js';
+export interface ScreenCaptureOptions {
+    /** Must match a `<Screen id="...">` JSX block in the MDX file. */
+    id: string;
+    /** Absolute or cwd-relative path to the `.mdx` file. */
+    mdxPath: string;
+    /**
+     * Override the locator used as the snapshot root. Defaults to
+     * the page's `body` element. Useful when the test is scoped to
+     * a specific dialog or section.
+     */
+    rootLocator?: Locator;
+    /**
+     * Override the HTML attribute whitelist for `annot:attributes`
+     * collection. Default is `DEFAULT_ATTR_WHITELIST` — covers the
+     * common form-control + accessibility attrs.
+     */
+    attributeWhitelist?: readonly string[];
+}
+export interface Screen {
+    capture(opts: ScreenCaptureOptions): Promise<void>;
+}
+/**
+ * HTML attributes captured into the `annot:attributes` block by
+ * default. Focused on form-control + accessibility shape — the
+ * stuff a screen-specifications spreadsheet / operation manual cares about per element.
+ *
+ * Hosts can override per-call via `opts.attributeWhitelist`.
+ */
+export declare const DEFAULT_ATTR_WHITELIST: readonly string[];
+/**
+ * `test = annotatorTest.extend({ screen })` — drop-in for
+ * `@playwright/test`'s `test` plus a `screen` fixture for the
+ * docs flow. Tour files (`tests/docs/*.spec.ts`) import this
+ * `test` instead of `@playwright/test`:
+ *
+ * ```ts
+ * import { test } from "@ingcreators/annot-product-docs";
+ *
+ * test("login flow", async ({ page, screen }) => {
+ *   await page.goto("/login");
+ *   await screen.capture({
+ *     id: "login",
+ *     mdxPath: "docs/books/screen-spec/screens/SC-001-login.mdx",
+ *   });
+ * });
+ * ```
+ */
+export declare const test: import('@playwright/test').TestType<import('@playwright/test').PlaywrightTestArgs & import('@playwright/test').PlaywrightTestOptions & {
+    annotator: import('@ingcreators/annot-playwright').PlaywrightAnnotator;
+} & {
+    screen: Screen;
+}, import('@playwright/test').PlaywrightWorkerArgs & import('@playwright/test').PlaywrightWorkerOptions>;
+/**
+ * Standalone capture helper — same behaviour as
+ * `screen.capture(...)` but takes the `Page` directly. Exported
+ * so callers who build their own Playwright fixture (e.g.
+ * composing additional fixtures on top) can still drive the
+ * docs-sync flow.
+ *
+ * Idempotent: if `mdxPath` already has `annot:snapshot` /
+ * `annot:attributes` blocks, they're replaced in place; if not,
+ * they're appended. Files without `annot:` frontmatter throw —
+ * the fixture refuses to touch non-annot MDX.
+ */
+export declare function captureScreen(page: Page, opts: ScreenCaptureOptions): Promise<void>;
+/**
+ * Walk the overlays in a `<Screen>`, resolve each one's `match`
+ * against the live page, and emit a YAML block of the form:
+ *
+ *   role "Name":
+ *     attrA: value
+ *     attrB: value
+ *
+ * Only overlays whose `match` resolves to exactly one element
+ * contribute a section. Overlays with zero hits or multiple
+ * hits are skipped (the drift detector in Phase 1 PR 4 raises
+ * those — duplicating the diagnostic here would be noisy).
+ */
+export declare function collectAttributesYaml(page: Page, overlays: OverlaySpec[], whitelist: readonly string[]): Promise<string>;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { filterAnnotMdxFiles, main, walkMdx, } from './cli.js';
+export { annotDocsConfigSchema, annotFrontmatterSchema, defineConfig, isScreenRole, } from './config.js';
+export type { DetectDriftOptions, DriftFinding, DriftKind, DriftSeverity, } from './drift.js';
+export { detectDrift, detectDriftFromYaml, isLintableScreen, lintableScreens, summariseDrift, } from './drift.js';
+export type { Screen, ScreenCaptureOptions } from './fixture.js';
+export { captureScreen, collectAttributesYaml, DEFAULT_ATTR_WHITELIST, test, } from './fixture.js';
+export type { ParseMdxOptions } from './mdx.js';
+export { parseMdx, parseMdxFile, updateCommentBlocks } from './mdx.js';
+export type { ResolveFailureKind, ResolveResult, SnapshotEntry, } from './resolver.js';
+export { parseSnapshot, resolveMatch, resolveOverlays, } from './resolver.js';
+export type { AnnotCommentBlocks, AnnotFrontmatter, AnnotFrontmatterRole, AnnotMeta, AnnotXlsxConfig, HistoryEntrySpec, MatchKey, OverlayIntent, OverlaySpec, ParsedMdx, ScreenListSpec, ScreenSpec, TransitionSpec, } from './types.js';
+export type { AnnotDocsConfig, BookConfig } from './types-config.js';