cgraphx 1.2.0 → 1.3.1

package/dist/api-test/report.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Report + list phase — Phase 6 of the api-test pipeline (T-60).
+ *
+ * Spec contract:
+ *   - `generateReport(projectRoot, date)` aggregates the day's JSONL run
+ *     history + the static `.md` catalog into a Markdown report written to
+ *     `docs/api-test/report-YYYY-MM-DD.md`.
+ *   - `listEndpoints(projectRoot, filters)` renders a terminal table of every
+ *     endpoint discovered from the `.md` catalog, with the most recent run
+ *     result joined from JSONL history.
+ *
+ * Aggregation rules (spec §5.6):
+ *   - total endpoints   = number of `.md` files (the catalog is the source of
+ *     truth for "what interfaces exist").
+ *   - passed / failed   = count of JSONL lines with `passed: true` / `false`.
+ *   - skip count        = number of `.md` files whose frontmatter `status` is
+ *     `skip`.
+ *   - per-service rate  = group JSONL runs by `service`, passed/total.
+ *   - failure list      = JSONL lines with `passed: false` (endpoint + error).
+ *   - skip list         = `.md` files with `status: skip` (endpoint + skip_reason).
+ *   - avg duration      = mean of `duration_ms` across all JSONL lines for the date.
+ *   - p99 duration      = nearest-rank 99th percentile of `duration_ms` (degenerates
+ *     to max for small N — that's expected, not a bug).
+ *
+ * JSONL missing for the requested date → `ReportError` (CLI exit code 2).
+ *
+ * Independent subsystem — only depends on `node:fs` / `node:path` and the
+ * subsystem's own `test-history.ts` / `errors.ts` / `types.ts`. No imports
+ * from `src/extraction/` / `src/resolution/` / `src/db/`, and no third-party
+ * YAML / table libraries (frontmatter is parsed with a hand-rolled scalar
+ * parser; the terminal table is rendered with manual padding).
+ */
+import type { TestRun } from './types';
+/** Parsed frontmatter for a catalog `.md` file. */
+export interface EndpointMd {
+    /** `<svc_id>_<methodName>` — the endpoint identifier used in JSONL `endpoint`. */
+    endpoint: string;
+    svcId: string;
+    service: string;
+    method: string;
+    status: 'active' | 'skip';
+    skipReason: string | null;
+    /** Absolute path to the `.md` file. */
+    mdPath: string;
+}
+/** Aggregated report data — rendered into Markdown by `renderReport`. */
+export interface ReportData {
+    date: string;
+    totalEndpoints: number;
+    passedCount: number;
+    failedCount: number;
+    skipCount: number;
+    perService: Array<{
+        service: string;
+        total: number;
+        passed: number;
+        passRate: number;
+    }>;
+    failures: Array<{
+        endpoint: string;
+        service: string;
+        error: string | null;
+    }>;
+    skips: Array<{
+        endpoint: string;
+        service: string;
+        skipReason: string | null;
+    }>;
+    avgDurationMs: number;
+    p99DurationMs: number;
+}
+/** Filters applied by the `list` subcommand. */
+export interface ListFilters {
+    service?: string;
+    status?: 'active' | 'skip';
+    svcId?: string;
+}
+/** A row in the `list` terminal table. */
+export interface ListRow {
+    endpoint: string;
+    service: string;
+    svcId: string;
+    status: 'active' | 'skip';
+    /** 'true' / 'false' / '—' when no run history exists. */
+    lastRunResult: string;
+}
+/**
+ * Generate the Markdown report for a single day.
+ *
+ * Reads `<projectRoot>/.cgraphx/api-test/runs/<date>.jsonl` and every
+ * `docs/api-test/<service>/*.md` catalog file, aggregates statistics, and
+ * returns the Markdown content. Throws `ReportError` when the JSONL file
+ * for the requested date doesn't exist (the report has no run data to
+ * summarize — that's a hard error, not an empty report).
+ */
+export declare function generateReport(projectRoot: string, date: string): Promise<string>;
+/**
+ * Resolve the report output path: `<projectRoot>/docs/api-test/report-<date>.md`.
+ */
+export declare function reportFilePath(projectRoot: string, date: string): string;
+/**
+ * List every catalog endpoint with its most recent run result, after filters.
+ *
+ * The "most recent run" is found by scanning every `*.jsonl` file in the runs
+ * directory and picking the entry with the largest `ran_at` for each endpoint.
+ * Endpoints with no run history get `lastRunResult = '—'`.
+ */
+export declare function listEndpoints(projectRoot: string, filters?: ListFilters): ListRow[];
+/**
+ * Render `listEndpoints` output as a fixed-width terminal table with a header
+ * row and a separator line. Returns the empty string when there are no rows
+ * (the CLI prints a "no endpoints" notice instead).
+ */
+export declare function renderListTable(rows: ListRow[]): string;
+/**
+ * Read every `TestRun` from `<runsDir>/<date>.jsonl`. Throws `ReportError`
+ * when the file doesn't exist (the report cannot be summarized without run
+ * data — the spec says "选抛错,exit code 2").
+ */
+export declare function readRunsForDate(projectRoot: string, date: string): TestRun[];
+/**
+ * Parse a JSONL string into `TestRun[]`. Blank lines are skipped; malformed
+ * lines throw `ReportError` (a corrupted history file shouldn't silently
+ * produce wrong stats).
+ */
+export declare function parseJsonl(content: string): TestRun[];
+/** Convert a parsed JSONL object (snake_case keys) back into a `TestRun`. */
+declare function deserializeRun(obj: Record<string, unknown>): TestRun;
+/**
+ * Build a map of `endpoint → most recent TestRun` by scanning every JSONL
+ * file in the runs directory. Returns an empty map when the runs directory
+ * doesn't exist (a fresh project with no run history — `list` still works,
+ * every endpoint just shows `—`).
+ */
+export declare function readLatestRunByEndpoint(projectRoot: string): Map<string, TestRun>;
+/**
+ * Walk `docs/api-test/<service>/*.md` and parse each file's frontmatter into
+ * an `EndpointMd` record. Skips `report-*.md` files at the api-test root
+ * (those are this subsystem's own output, not catalog entries).
+ */
+export declare function readAllEndpoints(projectRoot: string): EndpointMd[];
+/**
+ * Parse the YAML frontmatter block (the text between `---` lines at the top
+ * of a `.md` file) into a string-keyed map.
+ *
+ * Scalar `key: value` pairs are extracted. Quoted scalars (`"..."` / `'...'`)
+ * are unquoted. The literal `null` becomes `null` in the map. Block scalars
+ * (`|-` followed by indented lines) and nested lists (`key:` + `- item`) are
+ * NOT parsed — the report/list phase only needs scalar fields (`svc_id`,
+ * `service`, `method`, `status`, `skip_reason`). Lines that look like list
+ * items or continuation lines (leading whitespace) are skipped.
+ */
+export declare function parseFrontmatter(content: string): Record<string, string | null>;
+/** Aggregate JSONL runs + `.md` catalog into `ReportData` for rendering. */
+export declare function aggregateReport(date: string, runs: TestRun[], endpoints: EndpointMd[]): ReportData;
+/**
+ * Nearest-rank percentile. For a sample of size N, the P-th percentile (where
+ * `p` is a fraction in [0, 1]) is the value at the 1-indexed position
+ * `ceil(p * N)` of the sorted (ascending) sample. For N=0 returns 0. For
+ * small N this degenerates to the max — that's the documented behavior, not
+ * a bug.
+ */
+export declare function percentile(values: number[], p: number): number;
+/** Render `ReportData` as a Markdown document. */
+export declare function renderReport(data: ReportData): string;
+/**
+ * Render a 2D string matrix as a fixed-width terminal table. The first row
+ * is treated as the header and separated from the body by a `---` divider
+ * line. Column widths are the max cell width in each column. Empty matrix
+ * returns the empty string.
+ */
+export declare function renderTable(rows: string[][]): string;
+/** Internal helpers re-exported for tests. */
+export declare const __INTERNAL_REPORT: {
+    DEFAULT_OUTPUT_DIR: string;
+    reportFilePath: typeof reportFilePath;
+    parseJsonl: typeof parseJsonl;
+    deserializeRun: typeof deserializeRun;
+    readLatestRunByEndpoint: typeof readLatestRunByEndpoint;
+    readAllEndpoints: typeof readAllEndpoints;
+    parseFrontmatter: typeof parseFrontmatter;
+    aggregateReport: typeof aggregateReport;
+    percentile: typeof percentile;
+    renderReport: typeof renderReport;
+    renderTable: typeof renderTable;
+};
+export {};
+//# sourceMappingURL=report.d.ts.map

package/dist/api-test/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/api-test/report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAKvC,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxF,QAAQ,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAC7E,KAAK,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0CAA0C;AAC1C,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,yDAAyD;IACzD,aAAa,EAAE,MAAM,CAAC;CACvB;AAID;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKvF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAExE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,EAAE,CA+BvF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAWvD;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAY5E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,EAAE,CAiBrD;AAED,6EAA6E;AAC7E,iBAAS,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAW7D;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CA4BjF;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,EAAE,CAsClE;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAiC/E;AAID,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EAAE,EACf,SAAS,EAAE,UAAU,EAAE,GACtB,UAAU,CAqDZ;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAM9D;AAID,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CA0DrD;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,CAiBpD;AAED,8CAA8C;AAC9C,eAAO,MAAM,iBAAiB;;;;;;;;;;;;CAY7B,CAAC"}