wehub-resource-sync
529 lines
21 KiB
TypeScript
529 lines
21 KiB
TypeScript
/**
|
|
* Shared manifest schema + parser.
|
|
*
|
|
* Used by audit.ts, validate-parity.ts, and capture-previews.ts so the
|
|
* three tools agree on:
|
|
* 1. the Manifest / ManifestDemo TypeScript shape
|
|
* 2. runtime shape validation of `manifest.yaml`
|
|
* 3. the tagged-union return type distinguishing missing /
|
|
* malformed / unreadable / ok
|
|
*/
|
|
|
|
import fs from "fs";
|
|
import yaml from "yaml";
|
|
|
|
/**
|
|
* Branded, non-empty demo id. Structurally a string (so downstream
|
|
* callers can still use `demo.id` in template strings, `Set<string>`
|
|
* membership, equality comparisons, etc.) but the branding prevents
|
|
* arbitrary strings from flowing into a `DemoId` slot without going
|
|
* through the `createDemoId` smart constructor. parseManifest is the
|
|
* sole production caller of that constructor; it validates non-empty
|
|
* at runtime and re-reports shape-malformed on failure.
|
|
*
|
|
* The `__brand` property is phantom-only — it does not exist at
|
|
* runtime. That keeps the branded type zero-cost while still giving
|
|
* the compiler a distinct nominal type for id values.
|
|
*/
|
|
export type DemoId = string & { readonly __brand: "DemoId" };
|
|
|
|
/**
|
|
* Smart constructor for `DemoId`. Returns the branded value on success
|
|
* or `null` if validation fails (non-string or empty string). Kept as
|
|
* `null`-returning rather than throwing so `parseManifest` can turn a
|
|
* failure into its usual `{kind:"malformed", subkind:"shape"}` result
|
|
* without crossing an exception boundary.
|
|
*
|
|
* The parameter type is `unknown` — this function sits at an API
|
|
* boundary (yaml.parse results, JSON-roundtripped demos, caller-supplied
|
|
* strings) where the compile-time type does not hold. A widened param
|
|
* keeps the runtime typeof guard alive rather than reducing to a dead
|
|
* check.
|
|
*/
|
|
export function createDemoId(s: unknown): DemoId | null {
|
|
if (typeof s !== "string" || s.length === 0) return null;
|
|
return s as DemoId;
|
|
}
|
|
|
|
/**
|
|
* One entry under `manifest.yaml :: demos[]`. Name is optional; id is
|
|
* required AND non-empty (checked at runtime by parseManifest, typed
|
|
* via the `DemoId` brand).
|
|
*
|
|
* Fields are `readonly`: parseManifest freezes the returned object so
|
|
* downstream consumers cannot mutate a demo after validation. The type
|
|
* matches the runtime freeze.
|
|
*/
|
|
export interface ManifestDemo {
|
|
readonly id: DemoId;
|
|
readonly name?: string;
|
|
/**
|
|
* Informational demos (e.g. cli-start): when set, the row surfaces this
|
|
* copy-pasteable command in the dashboard instead of a live preview.
|
|
* Such demos have no on-disk folder — parity / bundling skip them.
|
|
*/
|
|
readonly command?: string;
|
|
/**
|
|
* Relative URL path for the demo. `id` is the CATALOG identifier
|
|
* (stable; matched against spec/qa filenames and shell-side registry
|
|
* entries), whereas `route` is the deliberate URL / filesystem path
|
|
* (`/demos/<dir>` — resolved to `src/app/demos/<dir>/` by consumers
|
|
* that need the on-disk location, e.g. bundle-demo-content and
|
|
* validate-parity). The two are intentionally separate so renaming a
|
|
* catalog id does not mass-rewrite URLs (and vice versa).
|
|
*
|
|
* Optional at the type boundary for backward compatibility with test
|
|
* fixtures and historical manifests. When present, parseManifest
|
|
* validates it is a non-empty string starting with "/demos/".
|
|
* Consumers that need an on-disk demo directory should prefer
|
|
* `route` when present and fall back to `id`.
|
|
*/
|
|
readonly route?: string;
|
|
}
|
|
|
|
/**
|
|
* Union of the fields used by audit.ts / validate-parity.ts / capture-previews.ts.
|
|
*
|
|
* `slug` is REQUIRED: every manifest in showcase/integrations/ carries a
|
|
* slug, and none of the three consumers ever constructs or accepts a
|
|
* Manifest without one. Marking it required here lets downstream code
|
|
* drop `manifest.slug ?? "(unknown)"` fallbacks without TypeScript
|
|
* complaining. parseManifest enforces `slug` is a non-empty string at
|
|
* runtime, so the type matches reality.
|
|
*
|
|
* `name` and `deployed` remain optional: in practice not every manifest
|
|
* sets `name`, and `deployed` only appears when meaningful.
|
|
*
|
|
* `demos` is NON-optional but always set by parseManifest — an empty
|
|
* readonly array when the manifest omits the field. Callers iterate
|
|
* unconditionally instead of `?.` chaining.
|
|
*
|
|
* Fields are `readonly`: parseManifest deep-freezes the returned object
|
|
* (including the nested `demos` array), so the public type matches the
|
|
* runtime invariant.
|
|
*/
|
|
export interface Manifest {
|
|
readonly slug: string;
|
|
readonly name?: string;
|
|
readonly deployed?: boolean;
|
|
/**
|
|
* Deployed backend URL for this integration (e.g. the Railway public
|
|
* domain). Used by capture-previews.ts to navigate to each demo. Not
|
|
* required by audit.ts / validate-parity.ts, so it remains optional;
|
|
* callers that need it should check before use.
|
|
* parseManifest validates that, when present, it is a non-empty string.
|
|
*/
|
|
readonly backend_url?: string;
|
|
readonly demos: readonly ManifestDemo[];
|
|
}
|
|
|
|
/**
|
|
* Tagged union of manifest parse outcomes. Callers discriminate on
|
|
* `kind`:
|
|
*
|
|
* - "missing" — manifest.yaml does not exist on disk
|
|
* - "malformed" — file exists but its contents do not round-trip
|
|
* to a valid Manifest. Further split on `subkind`:
|
|
* "syntax" = YAML parser rejected the text outright
|
|
* (unterminated arrays, bad indentation);
|
|
* "shape" = YAML parsed but the resulting value
|
|
* does not match the Manifest shape
|
|
* (null/scalar top-level, non-array demos,
|
|
* demo missing id, duplicate demo id, etc.)
|
|
* - "unreadable" — file exists but readFileSync threw
|
|
* (permissions, I/O race, etc.)
|
|
* - "ok" — parse succeeded and shape validated
|
|
*
|
|
* The `subkind` discriminator on "malformed" lets callers route each
|
|
* failure mode distinctly: a "syntax" subkind flags a likely typo in
|
|
* the YAML source, whereas "shape" flags a schema-drift / validation
|
|
* problem (missing required field, wrong type, duplicate id, etc.).
|
|
*/
|
|
export type ParsedManifest =
|
|
| { kind: "ok"; manifest: Manifest }
|
|
| { kind: "missing" }
|
|
| { kind: "malformed"; subkind: "syntax" | "shape"; error: string }
|
|
| { kind: "unreadable"; error: string };
|
|
|
|
function errMsg(e: unknown): string {
|
|
return e instanceof Error ? e.message : String(e);
|
|
}
|
|
|
|
/**
|
|
* Describe a value for error messages. Distinguishes null/array from
|
|
* plain `typeof` because `typeof null === "object"` and
|
|
* `typeof [] === "object"` both hide the real shape from users.
|
|
*/
|
|
function describeType(v: unknown): string {
|
|
if (v === null) return "null";
|
|
if (Array.isArray(v)) return "array";
|
|
return typeof v;
|
|
}
|
|
|
|
/**
|
|
* `Object.hasOwn`-backed predicate that narrows `obj` to a type where
|
|
* `key` is known to exist. `Object.hasOwn` avoids inherited-property
|
|
* pitfalls of the raw `in` operator for any plain object, and pairs
|
|
* with the TS predicate so callers read `obj[key]` without further
|
|
* casts.
|
|
*/
|
|
function hasOwnProp<K extends string>(
|
|
obj: object,
|
|
key: K,
|
|
): obj is object & Record<K, unknown> {
|
|
return Object.hasOwn(obj, key);
|
|
}
|
|
|
|
/**
|
|
* Shared frozen empty-array sentinel reused across the "no demos
|
|
* declared" path. Every ok-result's `.demos` is this same frozen
|
|
* readonly value when the manifest omits demos, so callers can iterate
|
|
* unconditionally and the public `readonly` type matches the runtime
|
|
* freeze.
|
|
*/
|
|
const EMPTY_DEMOS: readonly ManifestDemo[] = Object.freeze([]);
|
|
|
|
/**
|
|
* Read + parse + validate a manifest.yaml at `filePath`. Returns a
|
|
* tagged-union `ParsedManifest`; never throws for content errors.
|
|
*
|
|
* The shape checks are intentionally strict:
|
|
* - top-level must be a plain object mapping (not null, scalar, or
|
|
* array) — otherwise downstream `.demos` / `.deployed` reads would
|
|
* TypeError at runtime;
|
|
* - `slug` must be a non-empty string (every consumer relies
|
|
* on it — missing slug is always a bug);
|
|
* - `name`, if present, must be a string;
|
|
* - `demos`, if present, must be an array of objects each with a
|
|
* string `id`;
|
|
* - `deployed`, if present, must be a boolean (YAML `"yes"` parses to
|
|
* a string, which would be silently treated as truthy without this
|
|
* check — classic footgun).
|
|
*
|
|
* Any shape failure produces
|
|
* `{ kind: "malformed", subkind: "shape", error }` with a
|
|
* human-readable reason. YAML parser failures produce
|
|
* `{ kind: "malformed", subkind: "syntax", error }` (distinct so CI can
|
|
* route syntax errors differently from schema-drift errors). Missing
|
|
* files produce `{ kind: "missing" }` (distinct from malformed so
|
|
* callers can emit different anomalies). Read errors (EACCES etc.)
|
|
* produce `{ kind: "unreadable" }` — we do NOT collapse them into
|
|
* malformed because the file's contents are not actually known to be
|
|
* invalid.
|
|
*/
|
|
export function parseManifest(
|
|
filePath: string,
|
|
dirSlug?: string,
|
|
): ParsedManifest {
|
|
// Empty-string dirSlug is a caller bug: `undefined` is the opt-out
|
|
// sentinel ("caller did not supply a dir slug"). If a caller's
|
|
// path.basename or similar produced `""` (trailing-slash path,
|
|
// typo), silently collapsing to undefined would hide the bug and
|
|
// skip the slug-mismatch guard. Surface as malformed-shape so the
|
|
// caller sees the error at the parser boundary.
|
|
if (dirSlug === "") {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `caller passed empty dirSlug (use undefined to opt out of the slug-check)`,
|
|
};
|
|
}
|
|
|
|
// Use statSync instead of fs.existsSync so ENOENT and non-ENOENT
|
|
// errno values (EACCES, ENOTDIR, etc.) are distinguished. existsSync
|
|
// CONFLATES these: a manifest whose parent dir is 0700 owned by
|
|
// another user returns false from existsSync, which would collapse
|
|
// an infrastructure failure into a benign "missing" signal. The
|
|
// long docstring on probeDir in validate-parity.ts explains the
|
|
// same anti-pattern — the fix is to stat + inspect errno.
|
|
try {
|
|
fs.statSync(filePath);
|
|
} catch (e) {
|
|
const code = (e as NodeJS.ErrnoException)?.code;
|
|
if (code === "ENOENT") return { kind: "missing" };
|
|
return { kind: "unreadable", error: errMsg(e) };
|
|
}
|
|
|
|
let raw: string;
|
|
try {
|
|
raw = fs.readFileSync(filePath, "utf-8");
|
|
} catch (e) {
|
|
return { kind: "unreadable", error: errMsg(e) };
|
|
}
|
|
|
|
let parsed: unknown;
|
|
try {
|
|
parsed = yaml.parse(raw);
|
|
} catch (e) {
|
|
return { kind: "malformed", subkind: "syntax", error: errMsg(e) };
|
|
}
|
|
|
|
// Top-level type guard. yaml.parse("") is null and yaml.parse("42") is
|
|
// 42 — neither is a manifest. Arrays also aren't valid (manifest.yaml
|
|
// is a mapping).
|
|
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected YAML object at top level, got ${
|
|
parsed === null ? "null (empty file?)" : describeType(parsed)
|
|
}`,
|
|
};
|
|
}
|
|
|
|
// At this point `parsed` is known to be a plain object mapping. We
|
|
// narrow each field access through `hasOwnProp` so the compiler does
|
|
// not need a blanket `as Record<string, unknown>` cast — every read
|
|
// below is narrowed by the predicate it just passed.
|
|
const obj: object = parsed;
|
|
|
|
// slug is required — every consumer (audit.ts / validate-parity.ts /
|
|
// capture-previews.ts) assumes a slug exists. A manifest without one is
|
|
// always a bug, not a tolerable edge case.
|
|
if (!hasOwnProp(obj, "slug")) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `missing required "slug" (non-empty string)`,
|
|
};
|
|
}
|
|
const slug = obj.slug;
|
|
if (typeof slug !== "string" || slug.length === 0) {
|
|
// `hasOwnProp(obj, "slug")` already passed above, so the key is
|
|
// present; the value can still be the empty string, null, or a
|
|
// non-string. `describeType` covers all of those uniformly.
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected "slug" to be a non-empty string, got ${describeType(slug)}`,
|
|
};
|
|
}
|
|
|
|
// Slug-mismatch guard. Every consumer derives the target
|
|
// package by computing `packagesDir/<slug>/manifest.yaml`, so if the
|
|
// manifest's declared slug disagrees with the directory that holds
|
|
// it, downstream tools would silently key a copy-paste or rename
|
|
// mistake into the wrong package. Catch at the parser so both tools
|
|
// report the drift the same way.
|
|
//
|
|
// Opt-in: callers pass the expected dir slug via the `dirSlug`
|
|
// parameter. When omitted (undefined), the check is skipped so
|
|
// existing tests and programmatic callers that don't operate against
|
|
// the packages tree continue to work. An explicit empty string is
|
|
// rejected at the top of the function as a caller bug — `undefined`
|
|
// is the opt-out sentinel; `""` is never a valid dir slug.
|
|
// The two production callers (audit.ts, validate-parity.ts) pass the
|
|
// slug they used to build the filePath.
|
|
const expectedDirSlug = typeof dirSlug === "string" ? dirSlug : undefined;
|
|
if (expectedDirSlug !== undefined && expectedDirSlug !== slug) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `slug mismatch: manifest declares "${slug}" but lives under dir "${expectedDirSlug}"`,
|
|
};
|
|
}
|
|
|
|
// name (optional) must be a string if present.
|
|
let name: string | undefined;
|
|
if (hasOwnProp(obj, "name") && obj.name !== undefined) {
|
|
if (typeof obj.name !== "string") {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected "name" to be a string, got ${describeType(obj.name)}`,
|
|
};
|
|
}
|
|
name = obj.name;
|
|
}
|
|
|
|
// deployed (optional) must be a real boolean if present.
|
|
let deployed: boolean | undefined;
|
|
if (hasOwnProp(obj, "deployed")) {
|
|
if (typeof obj.deployed !== "boolean") {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected "deployed" to be boolean, got ${describeType(obj.deployed)}`,
|
|
};
|
|
}
|
|
deployed = obj.deployed;
|
|
}
|
|
|
|
// backend_url (optional) must be a non-empty string if present. Not
|
|
// required by the audit/parity tools, so an absent field is fine.
|
|
let backendUrl: string | undefined;
|
|
if (hasOwnProp(obj, "backend_url") && obj.backend_url !== undefined) {
|
|
if (typeof obj.backend_url !== "string" || obj.backend_url.length === 0) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected "backend_url" to be a non-empty string, got ${describeType(obj.backend_url)}`,
|
|
};
|
|
}
|
|
backendUrl = obj.backend_url;
|
|
}
|
|
|
|
// demos must be an array of objects with non-empty string id. Both
|
|
// "key absent" and "explicit null" (YAML `demos:`) are treated as
|
|
// "no demos declared" — parseManifest normalizes to an empty frozen
|
|
// array so `Manifest.demos` is always set. If the key is present with
|
|
// a non-nullish value that is not an array, fall through and report.
|
|
let demos: readonly ManifestDemo[] = EMPTY_DEMOS;
|
|
if (hasOwnProp(obj, "demos") && obj.demos != null) {
|
|
const rawDemos = obj.demos;
|
|
if (!Array.isArray(rawDemos)) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected "demos" to be an array, got ${describeType(rawDemos)}`,
|
|
};
|
|
}
|
|
const validated: ManifestDemo[] = [];
|
|
// Duplicate-id detection: two demos with the same id cascade into
|
|
// double-counted coverage and double missing-demo-dir anomalies
|
|
// downstream. Reject at validation time so the error surfaces at
|
|
// the manifest, not at the consuming tool.
|
|
const seen = new Set<string>();
|
|
for (let i = 0; i < rawDemos.length; i++) {
|
|
const d: unknown = rawDemos[i];
|
|
if (d === null || typeof d !== "object" || Array.isArray(d)) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected demos[${i}] to be an object, got ${describeType(d)}`,
|
|
};
|
|
}
|
|
if (!hasOwnProp(d, "id") || typeof d.id !== "string") {
|
|
// Missing key or non-string value: describe the actual type so
|
|
// debuggers can distinguish this from the empty-string branch
|
|
// below. `describeType(undefined)` covers the missing-key case
|
|
// (the `hasOwnProp` narrowing means `d.id` is typed as unknown
|
|
// only inside the branch, but at runtime an absent key reads as
|
|
// undefined).
|
|
const actual = hasOwnProp(d, "id") ? d.id : undefined;
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected demos[${i}].id to be a string, got ${describeType(actual)}`,
|
|
};
|
|
}
|
|
const brandedId = createDemoId(d.id);
|
|
if (brandedId === null) {
|
|
// `d.id` is a string here (checked above); createDemoId only
|
|
// returns null for the empty-string case. Keep the "non-empty
|
|
// string" wording so this branch is distinct from the
|
|
// missing/non-string branch above.
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected demos[${i}].id to be a non-empty string`,
|
|
};
|
|
}
|
|
if (seen.has(brandedId)) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `duplicate demo id "${brandedId}" at demos[${i}]`,
|
|
};
|
|
}
|
|
seen.add(brandedId);
|
|
// demo-level `name` strictness: match the strictness applied to
|
|
// other fields so schema drift (present-but-wrong-type name)
|
|
// surfaces at the parser, not downstream. Absent `name` remains
|
|
// valid.
|
|
let demoName: string | undefined;
|
|
if (hasOwnProp(d, "name") && d.name !== undefined) {
|
|
if (typeof d.name !== "string") {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected demos[${i}].name to be a string, got ${describeType(d.name)}`,
|
|
};
|
|
}
|
|
demoName = d.name;
|
|
}
|
|
// demo-level `command`: optional informational demos (e.g. cli-start).
|
|
// When set, the row surfaces this copy-pasteable command in the
|
|
// dashboard instead of a live preview. Such demos have no on-disk
|
|
// folder — parity / bundling skip them.
|
|
let demoCommand: string | undefined;
|
|
if (hasOwnProp(d, "command") && d.command !== undefined) {
|
|
if (typeof d.command !== "string" || d.command.length === 0) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected demos[${i}].command to be a non-empty string, got ${describeType(d.command)}`,
|
|
};
|
|
}
|
|
demoCommand = d.command;
|
|
}
|
|
// demo-level `route`: optional. When present, must be a non-empty
|
|
// string beginning with "/demos/" so downstream consumers
|
|
// (bundle-demo-content, validate-parity) can uniformly strip that
|
|
// prefix to derive the on-disk demo directory. The `/demos/` guard
|
|
// catches accidental absolute URLs or bare segments that would
|
|
// silently point to the wrong directory at runtime.
|
|
let demoRoute: string | undefined;
|
|
if (hasOwnProp(d, "route") && d.route !== undefined) {
|
|
if (typeof d.route !== "string" || d.route.length === 0) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected demos[${i}].route to be a non-empty string, got ${describeType(d.route)}`,
|
|
};
|
|
}
|
|
if (!d.route.startsWith("/demos/")) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected demos[${i}].route to start with "/demos/", got "${d.route}"`,
|
|
};
|
|
}
|
|
// Reject exactly "/demos/" (empty tail segment). Downstream
|
|
// consumers strip the "/demos/" prefix to derive an on-disk
|
|
// directory name; an empty tail would point at the parent
|
|
// demos/ directory rather than a specific demo. Guard at the
|
|
// parser boundary so validate-parity / bundle-demo-content can
|
|
// treat a successful parse as a non-empty segment invariant.
|
|
if (d.route.length <= "/demos/".length) {
|
|
return {
|
|
kind: "malformed",
|
|
subkind: "shape",
|
|
error: `expected demos[${i}].route to have a non-empty segment after "/demos/", got "${d.route}"`,
|
|
};
|
|
}
|
|
demoRoute = d.route;
|
|
}
|
|
const demoEntry: {
|
|
id: DemoId;
|
|
name?: string;
|
|
command?: string;
|
|
route?: string;
|
|
} = {
|
|
id: brandedId,
|
|
};
|
|
if (demoName !== undefined) demoEntry.name = demoName;
|
|
if (demoCommand !== undefined) demoEntry.command = demoCommand;
|
|
if (demoRoute !== undefined) demoEntry.route = demoRoute;
|
|
validated.push(Object.freeze(demoEntry));
|
|
}
|
|
demos = Object.freeze(validated);
|
|
}
|
|
|
|
// Construct the result field-by-field from the narrowed locals so
|
|
// there is no `as unknown as Manifest` double-cast crossing the
|
|
// validation boundary. Each field below was checked individually
|
|
// above; the compiler tracks the narrowed type through the local
|
|
// bindings, so this object literal typechecks against Manifest
|
|
// without any casts. The final object is frozen so the `readonly`
|
|
// fields on Manifest match the runtime behavior.
|
|
const manifest: Manifest = Object.freeze({
|
|
slug,
|
|
...(name !== undefined ? { name } : {}),
|
|
...(deployed !== undefined ? { deployed } : {}),
|
|
...(backendUrl !== undefined ? { backend_url: backendUrl } : {}),
|
|
demos,
|
|
});
|
|
return { kind: "ok", manifest };
|
|
}
|