@ui-manifest-json/core 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrainRidge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @ui-manifest-json/core
+
+The shared `UiManifest` schema — as TypeScript types — plus the framework-agnostic helpers every
+extractor builds on.
+
+**You don't usually install this directly.** [`@ui-manifest-json/angular`][ng] and
+[`@ui-manifest-json/react`][react] depend on it. Install it on its own when you're *consuming*
+manifests and want the types, or writing an extractor for another framework.
+
+```bash
+npm install @ui-manifest-json/core
+```
+
+## What's in it
+
+```ts
+import type { UiManifest, RouteNode, ComponentNode, DomNode } from '@ui-manifest-json/core';
+
+const manifest: UiManifest = JSON.parse(await readFile('ui-manifest.json', 'utf8'));
+```
+
+The full shape is documented field by field in [docs/schema.md][schema]. The types are the source of
+truth; that page is the tour.
+
+Three runtime helpers ship alongside the types:
+
+| Export | What it does |
+|---|---|
+| `resolveRouteDependencyTree` | Splices each component's template into its parent's where the child's tag appears, recursively, with component-boundary and cycle markers. Framework-agnostic: you supply a `matchFn` that decides which tag maps to which component. |
+| `resolveFullPaths` | Walks a nested route tree and annotates each node with the full path a URL must have to reach it, `baseHref` applied. |
+| `collectRepoProvenance` / `generatorProvenance` | Reads the commit, remote, branch, dirty state and app root out of the git working tree, and the build id out of CI. Best-effort: outside a git tree every field is simply absent, which means the manifest is unpinned rather than that anything failed. |
+
+## Schema version
+
+`SCHEMA_VERSION` is `"2.0"`. A manifest carries it as `schemaVersion`, and it is the one field to
+check before trusting the rest — v2 made `app.baseHref` and `app.routerMode` required, and without
+those a route path cannot be matched against a real URL at all.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+[ng]: https://www.npmjs.com/package/@ui-manifest-json/angular
+[react]: https://www.npmjs.com/package/@ui-manifest-json/react
+[schema]: https://github.com/BrainRidge/ui-manifest/blob/main/docs/schema.md

package/dist/full-path.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolve every route's `fullPath` from the nested route tree.
+ *
+ * Framework-agnostic on purpose: Angular's `children`/`loadChildren` and React Router's nested
+ * `<Route>`/`children` produce the same `RouteNode` tree, so the join rule is the same and lives
+ * once. Both extractors call this after their own parsing.
+ */
+import type { RouteNode } from './types/route.js';
+/**
+ * Annotate `routes` (in place, recursively) with `fullPath`.
+ *
+ * `baseHref` is prepended so the result is what a URL actually looks like, not what the route
+ * config says — those differ for every app not served from the root, and the difference is
+ * invisible until a consumer tries to match a real URL and matches nothing.
+ *
+ * A wildcard gets no `fullPath` at all rather than an empty or synthesised one: it is a fallback,
+ * not a screen, and a consumer walking `fullPath` should skip it without having to know the
+ * convention.
+ *
+ * Note a wildcard's CHILDREN are still resolved. A `**` with children is unusual but legal, and the
+ * children are reachable even though the parent segment is not a location.
+ */
+export declare function resolveFullPaths(routes: RouteNode[], baseHref?: string): RouteNode[];
+//# sourceMappingURL=full-path.d.ts.map

package/dist/full-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"full-path.d.ts","sourceRoot":"","sources":["../src/full-path.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAYlD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,QAAQ,SAAM,GAAG,SAAS,EAAE,CAYjF"}

package/dist/full-path.js

@@ -0,0 +1,38 @@
+/** Route paths that match anything and therefore identify nothing. */
+const WILDCARDS = new Set(['**', '*']);
+function join(parent, segment) {
+    const left = parent.replace(/\/+$/, '');
+    const right = segment.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (!right)
+        return left || '/';
+    return `${left}/${right}`;
+}
+/**
+ * Annotate `routes` (in place, recursively) with `fullPath`.
+ *
+ * `baseHref` is prepended so the result is what a URL actually looks like, not what the route
+ * config says — those differ for every app not served from the root, and the difference is
+ * invisible until a consumer tries to match a real URL and matches nothing.
+ *
+ * A wildcard gets no `fullPath` at all rather than an empty or synthesised one: it is a fallback,
+ * not a screen, and a consumer walking `fullPath` should skip it without having to know the
+ * convention.
+ *
+ * Note a wildcard's CHILDREN are still resolved. A `**` with children is unusual but legal, and the
+ * children are reachable even though the parent segment is not a location.
+ */
+export function resolveFullPaths(routes, baseHref = '/') {
+    const base = `/${baseHref.replace(/^\/+/, '').replace(/\/+$/, '')}`.replace(/^\/$/, '');
+    const walk = (nodes, parent) => {
+        for (const node of nodes) {
+            const segment = node.path ?? '';
+            const here = WILDCARDS.has(segment.trim()) ? parent : join(parent, segment);
+            if (!WILDCARDS.has(segment.trim()))
+                node.fullPath = here || '/';
+            if (node.children?.length)
+                walk(node.children, here);
+        }
+    };
+    walk(routes, base);
+    return routes;
+}

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export * from './types/dom.js';
 export * from './types/component.js';
 export * from './types/route.js';
+export * from './types/provenance.js';
 export * from './types/dependency-graph.js';
 export * from './types/manifest.js';
+export { resolveFullPaths } from './full-path.js';
+export { collectRepoProvenance, generatorProvenance } from './provenance.js';
+export type { CollectProvenanceOptions } from './provenance.js';
 export { resolveRouteDependencyTree } from './resolve-tree.js';
 export type { MatchFn } from './resolve-tree.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,6 +1,9 @@
 export * from './types/dom.js';
 export * from './types/component.js';
 export * from './types/route.js';
+export * from './types/provenance.js';
 export * from './types/dependency-graph.js';
 export * from './types/manifest.js';
+export { resolveFullPaths } from './full-path.js';
+export { collectRepoProvenance, generatorProvenance } from './provenance.js';
 export { resolveRouteDependencyTree } from './resolve-tree.js';

package/dist/provenance.d.ts

@@ -0,0 +1,17 @@
+import type { GeneratorProvenance, RepoProvenance } from './types/provenance.js';
+export interface CollectProvenanceOptions {
+    /**
+     * Where the extractor is scanning. Becomes `appRoot`, relative to the repository root — and it
+     * is also the directory git is asked FROM, which matters more than it looks: `--dir` can point
+     * at a checkout that is not the one the command was run in, and asking git about the current
+     * directory would then pin the manifest to a completely unrelated repository's HEAD. That is the
+     * worst failure available here, because the result looks exactly like a correct pin.
+     */
+    targetDir: string;
+    /** Only a fallback origin for `appRoot` when the target is not in a git tree at all. */
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function collectRepoProvenance(options: CollectProvenanceOptions): RepoProvenance;
+export declare function generatorProvenance(name: string, version: string, passes: string[], env?: NodeJS.ProcessEnv): GeneratorProvenance;
+//# sourceMappingURL=provenance.d.ts.map

package/dist/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAoDjF,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,cAAc,CAsCvF;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EAAE,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,mBAAmB,CAGrB"}

package/dist/provenance.js

@@ -0,0 +1,104 @@
+/**
+ * Collect `RepoProvenance` from the git working tree, and `buildId` from CI.
+ *
+ * Every field is best-effort and every failure is silent-but-absent. This runs against arbitrary
+ * checkouts — a tarball with no `.git`, a shallow CI clone, a machine with no `git` on PATH — and
+ * none of those is an error: they mean the manifest is unpinned, which is a fact about the output
+ * rather than a failure to produce it. The one thing never done here is substituting a plausible
+ * value for a missing one: a branch name in place of a commit would look like a pin and move.
+ *
+ * `git` is invoked directly rather than via a dependency. It is one process per field, already on
+ * every machine that has a checkout to read, and the alternative is a dependency in a package whose
+ * whole appeal is that it has almost none.
+ */
+import { execFileSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { relative } from 'node:path';
+/**
+ * Resolve symlinks, or return the path unchanged.
+ *
+ * `git rev-parse --show-toplevel` reports a REAL path, so on any platform where the checkout sits
+ * under a symlink the two disagree and `relative()` produces an escape-hatch path full of `..`.
+ * macOS makes this the common case rather than an edge one — `/tmp` and `/var` are both symlinks
+ * into `/private` — so a manifest generated in a temp checkout would report an `appRoot` naming
+ * the developer's filesystem instead of a subtree of the repo.
+ */
+function realpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path; // the directory may not exist yet; a non-resolvable path is not a failure here
+    }
+}
+/** Run one git command, or return undefined. Never throws, never prints. */
+function git(args, cwd) {
+    try {
+        const out = execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 5000,
+        });
+        const value = out.trim();
+        return value || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The build identifier of the CI run, if this is one.
+ *
+ * Ordered by specificity, not popularity: a run id identifies one execution, where a build number
+ * can repeat across re-runs. Absent locally, which is correct — a developer's laptop has no build.
+ */
+function detectBuildId(env) {
+    return (env.GITHUB_RUN_ID ??
+        env.BUILD_BUILDID ?? // Azure Pipelines
+        env.CI_PIPELINE_ID ?? // GitLab
+        env.BUILDKITE_BUILD_ID ??
+        env.CIRCLE_WORKFLOW_ID ??
+        undefined);
+}
+export function collectRepoProvenance(options) {
+    const cwd = realpath(options.cwd);
+    const targetDir = realpath(options.targetDir);
+    // Every git question is asked from the SCANNED tree, not from the process's cwd — see
+    // `targetDir` above.
+    const root = git(['rev-parse', '--show-toplevel'], targetDir);
+    if (!root) {
+        // Not a git working tree. `appRoot` is still worth reporting relative to cwd — a consumer
+        // knowing which directory was scanned is useful even when it cannot know which commit.
+        const appRoot = relative(cwd, targetDir) || '.';
+        return { appRoot };
+    }
+    const commit = git(['rev-parse', 'HEAD'], targetDir);
+    // `--porcelain` is empty for a clean tree. Only meaningful once we know we have a commit:
+    // "dirty" without one says nothing a consumer can use.
+    const status = commit ? git(['status', '--porcelain'], targetDir) : undefined;
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'], targetDir);
+    const provenance = {
+        remoteUrl: git(['remote', 'get-url', 'origin'], targetDir),
+        commit,
+        // Committer date, ISO 8601 strict. Not the author date: two commits can share an author date
+        // after a rebase, and what orders two manifests is when the code landed.
+        commitTime: commit ? git(['show', '-s', '--format=%cI', 'HEAD'], targetDir) : undefined,
+        // A detached HEAD reports "HEAD", which is not a branch name and should not be recorded as one.
+        branch: branch && branch !== 'HEAD' ? branch : undefined,
+        dirty: commit ? Boolean(status) : undefined,
+        appRoot: relative(root, targetDir) || '.',
+    };
+    // Absent, not null/empty: a consumer testing `if (provenance.commit)` should not have to also
+    // test for the empty string, and JSON with explicit nulls everywhere reads as though something
+    // failed rather than as though it was never available.
+    for (const key of Object.keys(provenance)) {
+        if (provenance[key] === undefined)
+            delete provenance[key];
+    }
+    return provenance;
+}
+export function generatorProvenance(name, version, passes, env = process.env) {
+    const buildId = detectBuildId(env);
+    return buildId ? { name, version, buildId, passes } : { name, version, passes };
+}

package/dist/types/manifest.d.ts

@@ -1,11 +1,26 @@
 import type { ComponentNode } from './component.js';
 import type { RouteNode } from './route.js';
 import type { RouteDependencyTree } from './dependency-graph.js';
-export declare const SCHEMA_VERSION = "1.0";
+import type { AppIdentity, Coverage, CoverageScope, Provenance } from './provenance.js';
+/**
+ * Bumped to "2.0" for the `app` block, whose two fields are REQUIRED — see `AppIdentity`. A
+ * consumer needs exactly one field to test to know whether the routes it is about to read can be
+ * matched against real URLs at all, and that field is this one.
+ */
+export declare const SCHEMA_VERSION = "2.0";
 export type Framework = 'angular' | 'react';
 export interface UiManifest {
     schemaVersion: typeof SCHEMA_VERSION;
     framework: Framework;
+    /** Where the app is served from. Required: without it every route in this file is unmatchable
+     *  against a real URL, silently. See {@link AppIdentity}. */
+    app: AppIdentity;
+    /** Which commit, which extractor, which passes. Non-diffable — ignore it when diffing, the same
+     *  as `generatedAt`. */
+    provenance: Provenance;
+    /** Whether a missing route means "deleted" or "not looked at". See {@link Coverage}. */
+    coverage: Coverage;
+    coverageScope?: CoverageScope;
     /** ISO timestamp of generation. Not diff-relevant on its own — consumers diffing two
      *  manifests should ignore this field, since it changes on every run even with no UI change. */
     generatedAt: string;

package/dist/types/manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/types/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB;oGACgG;IAChG,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,wFAAwF;IACxF,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACxC;mGAC+F;IAC/F,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB"}
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/types/manifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAExF;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAC;AAEpC,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAE5C,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,OAAO,cAAc,CAAC;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB;iEAC6D;IAC7D,GAAG,EAAE,WAAW,CAAC;IACjB;4BACwB;IACxB,UAAU,EAAE,UAAU,CAAC;IACvB,wFAAwF;IACxF,QAAQ,EAAE,QAAQ,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;oGACgG;IAChG,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,wFAAwF;IACxF,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACxC;mGAC+F;IAC/F,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB"}

package/dist/types/manifest.js

@@ -1 +1,6 @@
-export const SCHEMA_VERSION = '1.0';
+/**
+ * Bumped to "2.0" for the `app` block, whose two fields are REQUIRED — see `AppIdentity`. A
+ * consumer needs exactly one field to test to know whether the routes it is about to read can be
+ * matched against real URLs at all, and that field is this one.
+ */
+export const SCHEMA_VERSION = '2.0';

package/dist/types/provenance.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Where a manifest came from: which app, which commit, which extractor run.
+ *
+ * v1 could answer "what does this UI contain" but not "which build is this" — so two manifests
+ * could only ever be compared against each other, never against a deployed thing. Everything here
+ * exists to make a manifest self-locating.
+ *
+ * **This whole block is non-diffable**, in the same sense `generatedAt` already is: `commit` and
+ * `buildId` change on every run even when the UI does not. `jq 'del(.generatedAt, .provenance)'`
+ * restores a document whose every remaining field changes only when the UI's structure does. That
+ * is why it is a segregated top-level block rather than fields sprinkled through `routes` and
+ * `components`.
+ */
+/** How the app's router turns a route path into a URL. */
+export type RouterMode = 'path' | 'hash';
+/**
+ * Where the app is served from, which is what decides whether a route path matches a real URL.
+ *
+ * Both fields are REQUIRED, and that is deliberate. Omitting either does not produce an error in
+ * any consumer — it produces a silent, total miss. An app served under `/portal/` renders
+ * `/portal/dashboard`; a manifest that says `dashboard` matches nothing, on every route, and looks
+ * exactly like a manifest for an app that simply has little in it. `useHash: true` fails the same
+ * way. A field whose absence is indistinguishable from a wrong answer has to be required.
+ */
+export interface AppIdentity {
+    /**
+     * The app's base path, from Angular's `<base href>` / `APP_BASE_HREF`, or React Router's
+     * `basename`. `"/"` when the app is served from the root — which is the common case, and is a
+     * real answer rather than a default standing in for "unknown".
+     */
+    baseHref: string;
+    /** `"hash"` for `useHash: true` / `HashRouter`, which puts the entire route after a `#`. */
+    routerMode: RouterMode;
+    /** How `baseHref`/`routerMode` were established. `"detected"` means read out of the source;
+     *  `"configured"` means the caller supplied them; `"default"` means neither, and the values are
+     *  the conventional ones — which a consumer should treat as a weaker claim. */
+    confidence: 'detected' | 'configured' | 'default';
+}
+/** The commit the source was in when the manifest was generated. */
+export interface RepoProvenance {
+    /** `origin`'s URL, as git reports it. Absent outside a git working tree. */
+    remoteUrl?: string;
+    /** Full commit sha. Absent outside a git working tree, and deliberately NOT defaulted to a
+     *  branch name: a branch moves, so a manifest pinned to one is not pinned at all. Its absence
+     *  marks the output as unpinned, which is information a consumer can act on. */
+    commit?: string;
+    /** Committer timestamp, ISO 8601. From git, never from a clock: it is what orders two manifests
+     *  that arrive out of sequence, and a generation timestamp would order them by when they were
+     *  uploaded rather than by which describes newer code. */
+    commitTime?: string;
+    branch?: string;
+    /** True when the working tree had uncommitted changes — so `commit` describes *most* of what was
+     *  extracted, not all of it. Silently reporting a commit for a dirty tree is how a manifest comes
+     *  to describe code that was never committed anywhere. */
+    dirty?: boolean;
+    /** The scanned directory, relative to the repository root. Every `filePath` in the manifest is
+     *  relative to this, so a consumer can reconstruct a repo-relative path without guessing. */
+    appRoot?: string;
+}
+/** Which extractor produced this, and what it actually ran. */
+export interface GeneratorProvenance {
+    name: string;
+    version: string;
+    /** The CI run that produced it, when one did (`GITHUB_RUN_ID` and friends). */
+    buildId?: string;
+    /**
+     * Analysis passes that ran, e.g. `["routes", "components", "dom", "dependency-graph"]`.
+     *
+     * The point is negative information: a consumer must be able to tell "this component has no DOM
+     * tree" from "the DOM pass never ran". Without it, every optional field is ambiguous between
+     * "absent" and "not looked for", and a consumer either re-runs unnecessarily or trusts a gap.
+     */
+    passes: string[];
+}
+export interface Provenance {
+    repo: RepoProvenance;
+    generator: GeneratorProvenance;
+}
+/**
+ * Whether this manifest describes the whole app or a named part of it.
+ *
+ * Load-bearing for anything that merges manifests over time. Given only a manifest that lacks a
+ * route, a consumer cannot tell whether the route was DELETED or merely not covered by this run —
+ * and guessing "not covered" means a deleted route lives forever, while guessing "deleted" throws
+ * away a real one. `"full"` is a claim that absence means deletion; `"partial"` is a claim that it
+ * does not, and `coverageScope` says what was actually looked at.
+ */
+export type Coverage = 'full' | 'partial';
+export interface CoverageScope {
+    routes?: string[];
+    paths?: string[];
+}
+//# sourceMappingURL=provenance.d.ts.map

package/dist/types/provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.d.ts","sourceRoot":"","sources":["../../src/types/provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,4FAA4F;IAC5F,UAAU,EAAE,UAAU,CAAC;IACvB;;mFAE+E;IAC/E,UAAU,EAAE,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC;CACnD;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;oFAEgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;8DAE0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;8DAE0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;iGAC6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,mBAAmB,CAAC;CAChC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB"}

package/dist/types/provenance.js

@@ -0,0 +1,14 @@
+/**
+ * Where a manifest came from: which app, which commit, which extractor run.
+ *
+ * v1 could answer "what does this UI contain" but not "which build is this" — so two manifests
+ * could only ever be compared against each other, never against a deployed thing. Everything here
+ * exists to make a manifest self-locating.
+ *
+ * **This whole block is non-diffable**, in the same sense `generatedAt` already is: `commit` and
+ * `buildId` change on every run even when the UI does not. `jq 'del(.generatedAt, .provenance)'`
+ * restores a document whose every remaining field changes only when the UI's structure does. That
+ * is why it is a segregated top-level block rather than fields sprinkled through `routes` and
+ * `components`.
+ */
+export {};

package/dist/types/route.d.ts

@@ -4,7 +4,21 @@ export interface RouteGuards {
 }
 export type ReactRoutingPattern = 'jsx-routes' | 'router-config' | 'file-based';
 export interface RouteNode {
+    /** This route's own segment, exactly as written in the source. */
     path: string;
+    /**
+     * The full path a URL must have to reach this route: every ancestor's `path` joined with this
+     * one, `baseHref` applied, and leading/trailing slashes normalised.
+     *
+     * Derivable by a consumer from the tree — but doing it here means one implementation instead of
+     * one per consumer, and it removes a specific way to get it wrong: two `''` children under
+     * different parents are the same `path` and different `fullPath`s, so a consumer keying on
+     * `path` silently collides them.
+     *
+     * Absent for a route that cannot BE a URL — a bare `**` wildcard matches every path and so
+     * identifies none, and giving it a `fullPath` would invite a consumer to treat it as a screen.
+     */
+    fullPath?: string;
     /** The resolved lazy-loaded target, e.g. Angular's loadComponent or a React <Route element>. */
     component?: {
         module: string;

package/dist/types/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,CAAC;AAEhF,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,gGAAgG;IAChG,SAAS,CAAC,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;IACvB,qFAAqF;IACrF,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACtC"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/types/route.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,eAAe,GAAG,YAAY,CAAC;AAEhF,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,SAAS,CAAC,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;IACvB,qFAAqF;IACrF,cAAc,CAAC,EAAE,mBAAmB,CAAC;CACtC"}

package/package.json

@@ -1,9 +1,25 @@
 {
   "name": "@ui-manifest-json/core",
-  "version": "0.1.0",
-  "description": "Shared JSON schema types and dependency-tree resolver for ui-manifest extractors.",
+  "version": "0.2.0",
+  "description": "Shared JSON schema types and framework-agnostic helpers for ui-manifest extractors.",
+  "keywords": [
+    "ui-manifest",
+    "schema",
+    "types",
+    "ast",
+    "static-analysis"
+  ],
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrainRidge/ui-manifest.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/BrainRidge/ui-manifest/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/BrainRidge/ui-manifest/issues"
+  },
   "engines": {
     "node": ">=20.6.0"
   },