@ploaness/governance 1.0.0

package/dist/container-freshness.d.ts

@@ -0,0 +1,102 @@
+/** A digest-pinned image reference, split into the parts a registry API addresses it by. */
+export interface ContainerReference {
+    /** The analyzer the image runs, which is the property that declares it. */
+    readonly tool: string;
+    /** The repository as written, such as `zricethezav/gitleaks`. */
+    readonly name: string;
+    readonly namespace: string;
+    readonly repository: string;
+    /** The human-readable version tag, which is what a newer release is compared against. */
+    readonly tag: string;
+    /** The immutable digest the pin actually resolves to. */
+    readonly digest: string;
+}
+/**
+ * A stable numeric tag, and the syntax family it belongs to.
+ *
+ * The family matters as much as the number. A repository commonly publishes several schemes at once -
+ * `2.14.0` beside `v2.14`, and a date-stamped line beside both - and comparing across them reports an
+ * "update" that is a different artefact rather than a newer one.
+ */
+export interface ContainerTag {
+    readonly raw: string;
+    /** The `v` a tag may lead with, kept because a repository that uses one uses it consistently. */
+    readonly prefix: string;
+    readonly parts: readonly number[];
+    /** True when the leading component reads as a year, which dates a line rather than versioning it. */
+    readonly isCalendar: boolean;
+}
+/**
+ * Read a digest-pinned reference into its addressable parts.
+ * @param tool the analyzer that runs the image, used to name the declaring property in a report.
+ * @param reference the `repository:tag@sha256:digest` reference.
+ * @returns the parts, or undefined when the reference is not pinned in that form.
+ */
+export declare const parseContainerReference: (tool: string, reference: string) => ContainerReference | undefined;
+/**
+ * Read a tag as a stable version, or refuse it.
+ * @param raw the tag as the registry publishes it.
+ * @returns the parsed tag, or undefined for anything that is not a stable numeric version.
+ */
+export declare const parseContainerTag: (raw: string) => ContainerTag | undefined;
+/**
+ * Whether two tags belong to the same published line, and are therefore comparable.
+ * @param one the pinned tag.
+ * @param other a candidate from the registry.
+ * @returns true when the prefix, the component count, and the calendar shape all agree.
+ */
+export declare const matchesTagScheme: (one: ContainerTag, other: ContainerTag) => boolean;
+/**
+ * Order two tags by version.
+ * @param one the first tag.
+ * @param other the second tag.
+ * @returns a negative number when `one` is older, positive when newer, zero when equal.
+ */
+export declare const compareContainerTags: (one: ContainerTag, other: ContainerTag) => number;
+/**
+ * The newest tag of the pinned tag's own scheme.
+ * @param current the pinned tag.
+ * @param available every tag the registry lists.
+ * @returns the newest comparable tag, which is `current` itself when nothing newer is published.
+ */
+export declare const latestOfScheme: (current: ContainerTag, available: readonly string[]) => ContainerTag;
+/** What a registry read established about one pinned image. */
+export interface ContainerInspection {
+    readonly reference: ContainerReference;
+    /** Every tag the repository publishes. */
+    readonly available: readonly string[];
+    /** The digest the pinned TAG resolves to today, which a mutable tag may have moved. */
+    readonly currentDigest: string;
+}
+/** What the rule decided about one pinned image, with the registry reads already done. */
+export interface ContainerVerdict {
+    readonly reference: ContainerReference;
+    /** The newer tag, or undefined when the pin is already the newest of its scheme. */
+    readonly newer: ContainerTag | undefined;
+    /** True when the declared tag no longer resolves to the digest pinned beside it. */
+    readonly hasDrifted: boolean;
+    /** What the declared tag resolves to now, which the drift line names beside the pin. */
+    readonly currentDigest: string;
+}
+/**
+ * Judge one inspected image.
+ * @param inspection the reference and what the registry answered about it.
+ * @returns the newer tag if one exists, and whether the declared tag has been repointed.
+ */
+export declare const judgeContainer: (inspection: ContainerInspection) => ContainerVerdict;
+/**
+ * The report line for an image with a newer tag available.
+ * @param reference the pinned image.
+ * @param newer the newer tag.
+ * @param newerDigest the digest that tag resolves to, which is what replaces the pin.
+ * @returns one line naming the declaring property and the replacement reference.
+ */
+export declare const describeContainerUpdate: (reference: ContainerReference, newer: ContainerTag, newerDigest: string) => string;
+/**
+ * The report line for a tag that no longer resolves to the digest pinned beside it.
+ * @param reference the pinned image.
+ * @param currentDigest the digest the tag resolves to now.
+ * @returns one line naming the declaring property and both digests.
+ */
+export declare const describeContainerDrift: (reference: ContainerReference, currentDigest: string) => string;
+//# sourceMappingURL=container-freshness.d.ts.map

package/dist/container-freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-freshness.d.ts","sourceRoot":"","sources":["../src/container-freshness.ts"],"names":[],"mappings":"AAWA,4FAA4F;AAC5F,MAAM,WAAW,kBAAkB;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,qGAAqG;IACrG,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAC7B;AA8BD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAClC,MAAM,MAAM,EACZ,WAAW,MAAM,KAChB,kBAAkB,GAAG,SAiBvB,CAAA;AAQD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,KAAG,YAAY,GAAG,SAY9D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,YAAY,EAAE,OAAO,YAAY,KAAG,OAGrC,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,YAAY,EAAE,OAAO,YAAY,KAAG,MACxC,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,YAAY,EACrB,WAAW,SAAS,MAAM,EAAE,KAC3B,YAUF,CAAA;AAED,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAA;IACtC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,uFAAuF;IACvF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAA;IACtC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;IACxC,oFAAoF;IACpF,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B,wFAAwF;IACxF,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,YAAY,mBAAmB,KAAG,gBAahE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GAClC,WAAW,kBAAkB,EAC7B,OAAO,YAAY,EACnB,aAAa,MAAM,KAClB,MAEkD,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,WAAW,kBAAkB,EAC7B,eAAe,MAAM,KACpB,MAE2F,CAAA"}

package/dist/container-freshness.js

@@ -0,0 +1,129 @@
+// A stable tag is numeric and has at least two components. One component cannot be told apart from a
+// build number, and anything carrying a suffix - `-alpine`, `-rc1`, `-debug` - is either a variant or a
+// prerelease, neither of which a pin should move to on its own.
+const STABLE_TAG = /^(?<prefix>v?)(?<version>\d+(?:\.\d+)+)$/;
+const PINNED_REFERENCE = /^(?<name>[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*):(?<tag>[A-Za-z0-9][\w.-]*)@(?<digest>sha256:[0-9a-f]{64})$/;
+// Ordered by component rather than by the semver rule `dependency-freshness.ts` implements. A tag has
+// no prerelease - the pattern above refuses any suffix - and its component COUNT is meaningful here,
+// which a three-position core discards: it would read `2024.1` and `2024.1.0` as one version and drop a
+// fourth component entirely. Different questions, so a different comparison rather than a shared one.
+const compareParts = (one, other) => {
+    const width = Math.max(one.length, other.length);
+    const differences = Array.from({ length: width }, (_, index) => (one[index] ?? 0) - (other[index] ?? 0));
+    return differences.find((difference) => difference !== 0) ?? 0;
+};
+// A repository name is exactly one namespace and one repository, so the split takes both and no more.
+const NAME_PARTS = 2;
+const YEAR_LENGTH = 4;
+const FIRST_CALENDAR_YEAR = 2000;
+const LAST_CALENDAR_YEAR = 2099;
+/**
+ * Read a digest-pinned reference into its addressable parts.
+ * @param tool the analyzer that runs the image, used to name the declaring property in a report.
+ * @param reference the `repository:tag@sha256:digest` reference.
+ * @returns the parts, or undefined when the reference is not pinned in that form.
+ */
+export const parseContainerReference = (tool, reference) => {
+    const found = PINNED_REFERENCE.exec(reference);
+    if (found?.groups === undefined) {
+        return undefined;
+    }
+    const name = found.groups['name'] ?? '';
+    const [namespace, repo] = name.split('/', NAME_PARTS);
+    return namespace === undefined || repo === undefined
+        ? undefined
+        : {
+            tool,
+            name,
+            namespace,
+            repository: repo,
+            tag: found.groups['tag'] ?? '',
+            digest: found.groups['digest'] ?? '',
+        };
+};
+const isCalendarLead = (lead) => lead !== undefined &&
+    String(lead).length === YEAR_LENGTH &&
+    lead >= FIRST_CALENDAR_YEAR &&
+    lead <= LAST_CALENDAR_YEAR;
+/**
+ * Read a tag as a stable version, or refuse it.
+ * @param raw the tag as the registry publishes it.
+ * @returns the parsed tag, or undefined for anything that is not a stable numeric version.
+ */
+export const parseContainerTag = (raw) => {
+    const found = STABLE_TAG.exec(raw);
+    if (found?.groups === undefined) {
+        return undefined;
+    }
+    const parts = (found.groups['version'] ?? '').split('.').map(Number);
+    return {
+        raw,
+        prefix: found.groups['prefix'] ?? '',
+        parts,
+        isCalendar: isCalendarLead(parts[0]),
+    };
+};
+/**
+ * Whether two tags belong to the same published line, and are therefore comparable.
+ * @param one the pinned tag.
+ * @param other a candidate from the registry.
+ * @returns true when the prefix, the component count, and the calendar shape all agree.
+ */
+export const matchesTagScheme = (one, other) => one.prefix === other.prefix &&
+    one.parts.length === other.parts.length &&
+    one.isCalendar === other.isCalendar;
+/**
+ * Order two tags by version.
+ * @param one the first tag.
+ * @param other the second tag.
+ * @returns a negative number when `one` is older, positive when newer, zero when equal.
+ */
+export const compareContainerTags = (one, other) => compareParts(one.parts, other.parts);
+/**
+ * The newest tag of the pinned tag's own scheme.
+ * @param current the pinned tag.
+ * @param available every tag the registry lists.
+ * @returns the newest comparable tag, which is `current` itself when nothing newer is published.
+ */
+export const latestOfScheme = (current, available) => {
+    const comparable = available
+        .map((raw) => parseContainerTag(raw))
+        .filter((tag) => tag !== undefined)
+        .filter((tag) => matchesTagScheme(current, tag));
+    return comparable.reduce((newest, tag) => compareContainerTags(tag, newest) > 0 ? tag : newest, current);
+};
+/**
+ * Judge one inspected image.
+ * @param inspection the reference and what the registry answered about it.
+ * @returns the newer tag if one exists, and whether the declared tag has been repointed.
+ */
+export const judgeContainer = (inspection) => {
+    const current = parseContainerTag(inspection.reference.tag);
+    const newest = current === undefined ? undefined : latestOfScheme(current, inspection.available);
+    return {
+        reference: inspection.reference,
+        newer: newest === undefined || current === undefined || compareContainerTags(newest, current) <= 0
+            ? undefined
+            : newest,
+        hasDrifted: inspection.currentDigest !== inspection.reference.digest,
+        currentDigest: inspection.currentDigest,
+    };
+};
+/**
+ * The report line for an image with a newer tag available.
+ * @param reference the pinned image.
+ * @param newer the newer tag.
+ * @param newerDigest the digest that tag resolves to, which is what replaces the pin.
+ * @returns one line naming the declaring property and the replacement reference.
+ */
+export const describeContainerUpdate = (reference, newer, newerDigest) => `update ${reference.tool} ${reference.name}:${reference.tag} -> ${newer.raw}; ` +
+    `pin ${reference.name}:${newer.raw}@${newerDigest}`;
+/**
+ * The report line for a tag that no longer resolves to the digest pinned beside it.
+ * @param reference the pinned image.
+ * @param currentDigest the digest the tag resolves to now.
+ * @returns one line naming the declaring property and both digests.
+ */
+export const describeContainerDrift = (reference, currentDigest) => `note ${reference.tool} ${reference.name}:${reference.tag} is pinned to ${reference.digest} ` +
+    `but that tag now resolves to ${currentDigest}; the pin still names the bytes it always did`;
+//# sourceMappingURL=container-freshness.js.map

package/dist/container-freshness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-freshness.js","sourceRoot":"","sources":["../src/container-freshness.ts"],"names":[],"mappings":"AAyCA,qGAAqG;AACrG,wGAAwG;AACxG,gEAAgE;AAChE,MAAM,UAAU,GAAW,0CAA0C,CAAA;AAErE,MAAM,gBAAgB,GACpB,iHAAiH,CAAA;AAEnH,sGAAsG;AACtG,qGAAqG;AACrG,wGAAwG;AACxG,sGAAsG;AACtG,MAAM,YAAY,GAAG,CAAC,GAAsB,EAAE,KAAwB,EAAU,EAAE;IAChF,MAAM,KAAK,GAAW,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IACxD,MAAM,WAAW,GAAsB,KAAK,CAAC,IAAI,CAC/C,EAAE,MAAM,EAAE,KAAK,EAAE,EACjB,CAAC,CAAU,EAAE,KAAa,EAAU,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAC/E,CAAA;IACD,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,UAAkB,EAAW,EAAE,CAAC,UAAU,KAAK,CAAC,CAAC,IAAI,CAAC,CAAA;AACjF,CAAC,CAAA;AAED,sGAAsG;AACtG,MAAM,UAAU,GAAW,CAAC,CAAA;AAE5B,MAAM,WAAW,GAAW,CAAC,CAAA;AAC7B,MAAM,mBAAmB,GAAW,IAAI,CAAA;AACxC,MAAM,kBAAkB,GAAW,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,IAAY,EACZ,SAAiB,EACe,EAAE;IAClC,MAAM,KAAK,GAA2B,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;IACtE,IAAI,KAAK,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,IAAI,GAAW,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAA;IAC/C,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,GAAsB,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC,CAAA;IACxE,OAAO,SAAS,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS;QAClD,CAAC,CAAC,SAAS;QACX,CAAC,CAAC;YACE,IAAI;YACJ,IAAI;YACJ,SAAS;YACT,UAAU,EAAE,IAAI;YAChB,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE;YAC9B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;SACrC,CAAA;AACP,CAAC,CAAA;AAED,MAAM,cAAc,GAAG,CAAC,IAAwB,EAAW,EAAE,CAC3D,IAAI,KAAK,SAAS;IAClB,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,WAAW;IACnC,IAAI,IAAI,mBAAmB;IAC3B,IAAI,IAAI,kBAAkB,CAAA;AAE5B;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAW,EAA4B,EAAE;IACzE,MAAM,KAAK,GAA2B,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC1D,IAAI,KAAK,EAAE,MAAM,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,KAAK,GAAsB,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACvF,OAAO;QACL,GAAG;QACH,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QACpC,KAAK;QACL,UAAU,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACrC,CAAA;AACH,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,GAAiB,EAAE,KAAmB,EAAW,EAAE,CAClF,GAAG,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;IAC3B,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,KAAK,CAAC,MAAM;IACvC,GAAG,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU,CAAA;AAErC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAiB,EAAE,KAAmB,EAAU,EAAE,CACrF,YAAY,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;AAEtC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,OAAqB,EACrB,SAA4B,EACd,EAAE;IAChB,MAAM,UAAU,GAA4B,SAAS;SAClD,GAAG,CAAC,CAAC,GAAW,EAA4B,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;SACtE,MAAM,CAAC,CAAC,GAA6B,EAAuB,EAAE,CAAC,GAAG,KAAK,SAAS,CAAC;SACjF,MAAM,CAAC,CAAC,GAAiB,EAAW,EAAE,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAA;IACzE,OAAO,UAAU,CAAC,MAAM,CACtB,CAAC,MAAoB,EAAE,GAAiB,EAAgB,EAAE,CACxD,oBAAoB,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EACtD,OAAO,CACR,CAAA;AACH,CAAC,CAAA;AAsBD;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,UAA+B,EAAoB,EAAE;IAClF,MAAM,OAAO,GAA6B,iBAAiB,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;IACrF,MAAM,MAAM,GACV,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,SAAS,CAAC,CAAA;IACnF,OAAO;QACL,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,KAAK,EACH,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,IAAI,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC;YACzF,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,MAAM;QACZ,UAAU,EAAE,UAAU,CAAC,aAAa,KAAK,UAAU,CAAC,SAAS,CAAC,MAAM;QACpE,aAAa,EAAE,UAAU,CAAC,aAAa;KACxC,CAAA;AACH,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,SAA6B,EAC7B,KAAmB,EACnB,WAAmB,EACX,EAAE,CACV,UAAU,SAAS,CAAC,IAAI,IAAI,SAAS,CAAC,IAAI,IAAI,SAAS,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI;IAC/E,OAAO,SAAS,CAAC,IAAI,IAAI,KAAK,CAAC,GAAG,IAAI,WAAW,EAAE,CAAA;AAErD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,SAA6B,EAC7B,aAAqB,EACb,EAAE,CACV,QAAQ,SAAS,CAAC,IAAI,IAAI,SAAS,CAAC,IAAI,IAAI,SAAS,CAAC,GAAG,iBAAiB,SAAS,CAAC,MAAM,GAAG;IAC7F,gCAAgC,aAAa,+CAA+C,CAAA"}

package/dist/dependency-freshness.d.ts

@@ -0,0 +1,129 @@
+/** The build impact of a dependency's drift from its latest published release. */
+export type FreshnessVerdict = 'ok' | 'update' | 'fail';
+/** Major-version gap (`latest.major - current.major`) at or above which the gate FAILS the build. */
+export declare const MAJOR_FAIL_THRESHOLD: number;
+/** A dependency version parsed into its numeric core plus any prerelease tag. */
+export interface ParsedVersion {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly prerelease: string;
+}
+/**
+ * Parse a version or range string into its numeric core plus any prerelease tag, tolerating a leading
+ * range operator (`^`, `~`, `>=`) or `v` and trailing build metadata. Returns `undefined` when there
+ * is no leading numeric major - for example `workspace:*`, `link:../pkg`, `*`, or a missing latest - so
+ * the caller treats such a dependency as unclassifiable and skips it.
+ * @param raw the version or range string to parse.
+ * @returns the parsed core and prerelease, or `undefined` when no numeric major is present.
+ */
+export declare const parseVersion: (raw: string) => ParsedVersion | undefined;
+/**
+ * Classify how far a current version has drifted from the latest published version. Unclassifiable
+ * inputs (a version that does not parse, such as `workspace:*` or an absent latest) are `ok` and
+ * silently skipped. Otherwise the verdict is `fail` when the latest major is MAJOR_FAIL_THRESHOLD or
+ * more ahead, `update` when the current is strictly behind by any lesser amount (a single major, or a
+ * minor/patch), and `ok` when the current is level with or ahead of the latest. Because the major gap
+ * uses the literal `major` field, a `0.x` package is compared on that leading `0` (so `0.35.2` to
+ * `0.35.3` needs an update, and only a jump to `2.x` fails).
+ * @param current the version currently declared/installed.
+ * @param latest the latest version published to the registry.
+ * @returns the freshness verdict for the pair.
+ */
+export declare const classifyFreshness: (current: string, latest: string) => FreshnessVerdict;
+/** One dependency, plugin, or parent as some manifest of the repository declares it. */
+export interface DeclaredCoordinate {
+    /** The package name, or a `$schema` pseudo-dependency label. */
+    readonly name: string;
+    /** The manifest that declares it, so a finding names what the reader has to open. */
+    readonly owner: string;
+    /** The version currently declared/installed. */
+    readonly current: string;
+    /**
+     * True when the manifest is one the project INHERITS rather than one it wrote.
+     *
+     * The measurement is the same either way. What differs is who the finding belongs to: a project
+     * cannot edit a version ploaness declares, so the repair is upgrading the harness, and the build is
+     * not stopped over it. `HARNESS_EXCEPTIONS` in `vulnerability-policy.ts` draws the same distinction
+     * for an advisory carried by ploaness's own chain, and for the same reason.
+     */
+    readonly isInherited: boolean;
+}
+/** A declared coordinate paired with what the registry answered for it. */
+export interface DependencyStatus extends DeclaredCoordinate {
+    /** The latest version published to the registry. */
+    readonly latest: string;
+}
+/** One parsed manifest, with the path a finding will name. */
+export interface ManifestSource {
+    readonly path: string;
+    readonly packageJson: unknown;
+    /** True for a manifest the project inherits rather than one it tracks. */
+    readonly isInherited: boolean;
+}
+/**
+ * How the inheritance walk reaches one manifest from another.
+ *
+ * Injected so this module performs no I/O: the CLI supplies a resolver over the real filesystem, and a
+ * spec supplies one over a literal map. Which manifests a project inherits is a decision about what the
+ * standard counts, and a decision belongs where it can be tested without building an install.
+ */
+export interface ManifestResolver {
+    /** The manifest `packageName` resolves to FROM `fromManifest`, or undefined when unreachable. */
+    readonly locate: (packageName: string, fromManifest: string) => string | undefined;
+    /** The parsed manifest at a path. */
+    readonly read: (manifestPath: string) => unknown;
+}
+/**
+ * The manifests a project inherits, in discovery order, starting from the harness it declares.
+ *
+ * Walked rather than enumerated. A list of ploaness's packages would be a second copy of what their own
+ * manifests already declare, and a package added later would then be inherited by every consumer and
+ * read by nothing. The walk re-roots at each manifest, because a resolver's answer depends on where it
+ * is asked from, and it carries `visited` across siblings for two reasons: the packages form a diamond,
+ * so a shared one would otherwise be reported twice, and a cycle would otherwise not terminate.
+ * @param entry the manifest the project resolves the harness to, or undefined when it declares none.
+ * @param resolver how to reach and read a manifest.
+ * @returns each inherited manifest path once, the entry first.
+ */
+export declare const inheritedManifestPaths: (entry: string | undefined, resolver: ManifestResolver) => readonly string[];
+/**
+ * Read every declared coordinate out of every manifest, the project's own and the ones it inherits.
+ *
+ * A workspace declares its toolchain across several manifests, and reading only the root one left the
+ * analyzers ploaness itself runs on unmeasured. The standard counts an INHERITED manifest too, and the
+ * manifests deciding which analyzer versions a governed project's gates run are ploaness's own - none
+ * of which the project tracks, so a reader of tracked files alone can never see them.
+ *
+ * A name declared in two manifests stays two coordinates
+ * rather than collapsing into one: the two may pin different versions, and collapsing would hide
+ * whichever of them is stale. No sort is applied because none is needed - the caller hands over the
+ * manifests in the order git lists them, and a parsed object preserves the order its file declared, so
+ * the same tree yields the same report.
+ * @param manifests the parsed manifests, each with the path that declares it.
+ * @returns one coordinate per declaration.
+ */
+export declare const collectCoordinates: (manifests: readonly ManifestSource[]) => readonly DeclaredCoordinate[];
+/** A dependency status that classified as a non-`ok` verdict, carried through for reporting. */
+export interface FreshnessFinding extends DependencyStatus {
+    readonly verdict: 'update' | 'fail';
+}
+/**
+ * The findings for a set of dependency statuses; `ok` statuses are omitted.
+ *
+ * The split is by BUILD IMPACT, not by verdict: `failures` is what stops the run and `reported` is
+ * everything else worth printing. Each finding still carries the verdict it was measured at, so an
+ * inherited coordinate past the bound arrives in `reported` saying `fail` - which is the only way to
+ * report it honestly without stopping a project that cannot repair it.
+ */
+export interface FreshnessReport {
+    readonly failures: readonly FreshnessFinding[];
+    readonly reported: readonly FreshnessFinding[];
+}
+/**
+ * Partition dependency statuses by what each does to the build, dropping the `ok` ones.
+ * @param statuses the declared dependencies (and `$schema` pseudo-dependencies) to classify.
+ * @returns the findings that stop the run, and the rest of the report; both empty when all are fresh.
+ */
+export declare const findFreshnessViolations: (statuses: readonly DependencyStatus[]) => FreshnessReport;
+//# sourceMappingURL=dependency-freshness.d.ts.map

package/dist/dependency-freshness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-freshness.d.ts","sourceRoot":"","sources":["../src/dependency-freshness.ts"],"names":[],"mappings":"AAqBA,kFAAkF;AAClF,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEvD,qGAAqG;AACrG,eAAO,MAAM,oBAAoB,EAAE,MAAU,CAAA;AAE7C,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAQD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,aAAa,GAAG,SAW1D,CAAA;AA0BD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,EAAE,QAAQ,MAAM,KAAG,gBAUnE,CAAA;AAED,wFAAwF;AACxF,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,gDAAgD;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC9B;AAED,2EAA2E;AAC3E,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iGAAiG;IACjG,QAAQ,CAAC,MAAM,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAA;IAClF,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAA;CACjD;AA6BD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO,MAAM,GAAG,SAAS,EACzB,UAAU,gBAAgB,KACzB,SAAS,MAAM,EACkE,CAAA;AAEpF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,kBAAkB,GAC7B,WAAW,SAAS,cAAc,EAAE,KACnC,SAAS,kBAAkB,EAU3B,CAAA;AAEH,gGAAgG;AAChG,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,MAAM,CAAA;CACpC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAC9C,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAA;CAC/C;AAYD;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAAI,UAAU,SAAS,gBAAgB,EAAE,KAAG,eAiB/E,CAAA"}

package/dist/dependency-freshness.js

@@ -0,0 +1,161 @@
+// Dependency-freshness policy: the pure, unit-tested logic that reads the coordinates a repository
+// declares and classifies how far each has drifted from its latest published release. The `deps` gate in
+// packages/cli/src/checks/dependencies.ts reads the manifests and asks the registry.
+//
+// Policy: a declared dependency (transitive deps never count) whose current major version is
+// MAJOR_FAIL_THRESHOLD or more behind the latest published major FAILS the build; any lesser lag (a
+// single major behind, or a minor/patch behind) appears in the non-failing update report. The Biome config `$schema`
+// URL version is fed through the same classifier as a pseudo-dependency. There is no exemption list:
+// every declared dependency is MEASURED against the same bar, so a deliberately old pin that falls two
+// majors behind must be bumped or the pin dropped.
+//
+// One thing the bar does not decide is who the build stops. A coordinate an INHERITED manifest declares
+// is measured identically and reported at its real verdict, and it never fails the build: the version
+// belongs to ploaness, the project has no file in which to change it, and a gate that stopped every
+// consumer at once over a pin none of them can edit would be reporting ploaness's defect as theirs.
+// That is a statement about whose repair it is rather than an exemption from the measurement, which is
+// why the verdict survives into the report instead of being softened into an ordinary update.
+import { declaredDependencies } from './json-shapes.js';
+import { isHarnessPackage } from './version-policy.js';
+/** Major-version gap (`latest.major - current.major`) at or above which the gate FAILS the build. */
+export const MAJOR_FAIL_THRESHOLD = 2;
+// A leading range operator (`^ ~ >= <= = v`) or whitespace is tolerated, then the numeric core is
+// read into positional groups (major, minor, patch, prerelease); an optional `-prerelease` tag is
+// captured and build metadata after `+` is ignored. The core mirrors the `$schema` version regex the
+// `biome-schema` gate uses in packages/cli/src/checks/toolchain.ts.
+const VERSION_PATTERN = /^[\sv^~>=<]*(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([^+\s]+))?/;
+/**
+ * Parse a version or range string into its numeric core plus any prerelease tag, tolerating a leading
+ * range operator (`^`, `~`, `>=`) or `v` and trailing build metadata. Returns `undefined` when there
+ * is no leading numeric major - for example `workspace:*`, `link:../pkg`, `*`, or a missing latest - so
+ * the caller treats such a dependency as unclassifiable and skips it.
+ * @param raw the version or range string to parse.
+ * @returns the parsed core and prerelease, or `undefined` when no numeric major is present.
+ */
+export const parseVersion = (raw) => {
+    const match = VERSION_PATTERN.exec(raw);
+    if (match === null) {
+        return undefined;
+    }
+    return {
+        major: Number(match[1] ?? '0'),
+        minor: Number(match[2] ?? '0'),
+        patch: Number(match[3] ?? '0'),
+        prerelease: match[4] ?? '',
+    };
+};
+// Order two parsed versions: numeric core first, then a prerelease sorts BELOW the same core release
+// (the semver rule), so `1.0.0-rc.1` is behind `1.0.0`.
+const compareCore = (left, right) => {
+    if (left.major !== right.major) {
+        return left.major - right.major;
+    }
+    if (left.minor !== right.minor) {
+        return left.minor - right.minor;
+    }
+    if (left.patch !== right.patch) {
+        return left.patch - right.patch;
+    }
+    if (left.prerelease === right.prerelease) {
+        return 0;
+    }
+    if (left.prerelease === '') {
+        return 1;
+    }
+    if (right.prerelease === '') {
+        return -1;
+    }
+    return left.prerelease < right.prerelease ? -1 : 1;
+};
+/**
+ * Classify how far a current version has drifted from the latest published version. Unclassifiable
+ * inputs (a version that does not parse, such as `workspace:*` or an absent latest) are `ok` and
+ * silently skipped. Otherwise the verdict is `fail` when the latest major is MAJOR_FAIL_THRESHOLD or
+ * more ahead, `update` when the current is strictly behind by any lesser amount (a single major, or a
+ * minor/patch), and `ok` when the current is level with or ahead of the latest. Because the major gap
+ * uses the literal `major` field, a `0.x` package is compared on that leading `0` (so `0.35.2` to
+ * `0.35.3` needs an update, and only a jump to `2.x` fails).
+ * @param current the version currently declared/installed.
+ * @param latest the latest version published to the registry.
+ * @returns the freshness verdict for the pair.
+ */
+export const classifyFreshness = (current, latest) => {
+    const currentVersion = parseVersion(current);
+    const latestVersion = parseVersion(latest);
+    if (currentVersion === undefined || latestVersion === undefined) {
+        return 'ok';
+    }
+    if (latestVersion.major - currentVersion.major >= MAJOR_FAIL_THRESHOLD) {
+        return 'fail';
+    }
+    return compareCore(currentVersion, latestVersion) < 0 ? 'update' : 'ok';
+};
+const stepInto = (walk, manifestPath, resolver) => {
+    if (manifestPath === undefined || walk.visited.has(manifestPath)) {
+        return walk;
+    }
+    const entered = {
+        visited: new Set([...walk.visited, manifestPath]),
+        manifests: [...walk.manifests, manifestPath],
+    };
+    return Object.keys(declaredDependencies(resolver.read(manifestPath)))
+        .filter((name) => isHarnessPackage(name))
+        .reduce((carried, name) => stepInto(carried, resolver.locate(name, manifestPath), resolver), entered);
+};
+/**
+ * The manifests a project inherits, in discovery order, starting from the harness it declares.
+ *
+ * Walked rather than enumerated. A list of ploaness's packages would be a second copy of what their own
+ * manifests already declare, and a package added later would then be inherited by every consumer and
+ * read by nothing. The walk re-roots at each manifest, because a resolver's answer depends on where it
+ * is asked from, and it carries `visited` across siblings for two reasons: the packages form a diamond,
+ * so a shared one would otherwise be reported twice, and a cycle would otherwise not terminate.
+ * @param entry the manifest the project resolves the harness to, or undefined when it declares none.
+ * @param resolver how to reach and read a manifest.
+ * @returns each inherited manifest path once, the entry first.
+ */
+export const inheritedManifestPaths = (entry, resolver) => stepInto({ visited: new Set(), manifests: [] }, entry, resolver).manifests;
+/**
+ * Read every declared coordinate out of every manifest, the project's own and the ones it inherits.
+ *
+ * A workspace declares its toolchain across several manifests, and reading only the root one left the
+ * analyzers ploaness itself runs on unmeasured. The standard counts an INHERITED manifest too, and the
+ * manifests deciding which analyzer versions a governed project's gates run are ploaness's own - none
+ * of which the project tracks, so a reader of tracked files alone can never see them.
+ *
+ * A name declared in two manifests stays two coordinates
+ * rather than collapsing into one: the two may pin different versions, and collapsing would hide
+ * whichever of them is stale. No sort is applied because none is needed - the caller hands over the
+ * manifests in the order git lists them, and a parsed object preserves the order its file declared, so
+ * the same tree yields the same report.
+ * @param manifests the parsed manifests, each with the path that declares it.
+ * @returns one coordinate per declaration.
+ */
+export const collectCoordinates = (manifests) => manifests.flatMap((manifest) => Object.entries(declaredDependencies(manifest.packageJson)).map(([name, current]) => ({
+    name,
+    owner: manifest.path,
+    current,
+    isInherited: manifest.isInherited,
+})));
+// The one place the two questions are told apart: how far behind a coordinate is, and whether being
+// that far behind stops this build.
+const willStopTheBuild = (entry) => entry.verdict === 'fail' && !entry.status.isInherited;
+/**
+ * Partition dependency statuses by what each does to the build, dropping the `ok` ones.
+ * @param statuses the declared dependencies (and `$schema` pseudo-dependencies) to classify.
+ * @returns the findings that stop the run, and the rest of the report; both empty when all are fresh.
+ */
+export const findFreshnessViolations = (statuses) => {
+    // The verdict is computed once per status; the two reported groups are then filters over it rather
+    // than two lists filled in the same pass.
+    const judged = statuses.map((status) => ({
+        status,
+        verdict: classifyFreshness(status.current, status.latest),
+    }));
+    const findingsOf = (entries) => entries.flatMap((entry) => entry.verdict === 'ok' ? [] : [{ ...entry.status, verdict: entry.verdict }]);
+    return {
+        failures: findingsOf(judged.filter((entry) => willStopTheBuild(entry))),
+        reported: findingsOf(judged.filter((entry) => !willStopTheBuild(entry))),
+    };
+};
+//# sourceMappingURL=dependency-freshness.js.map

package/dist/dependency-freshness.js.map

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

package/dist/doc-blocks.d.ts

@@ -0,0 +1,13 @@
+export declare const DOCUMENTED_EXTENSIONS: readonly string[];
+/** The span of one documenting comment, as 1-based inclusive line numbers. */
+export interface DocBlock {
+    readonly line: number;
+    readonly endLine: number;
+}
+/**
+ * Find every documenting comment that is followed by another one rather than by what it documents.
+ * @param text the file contents, with lines separated by "\n" or "\r\n".
+ * @returns one entry per orphaned block, in reading order.
+ */
+export declare const findOrphanedDocBlocks: (text: string) => readonly DocBlock[];
+//# sourceMappingURL=doc-blocks.d.ts.map

package/dist/doc-blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-blocks.d.ts","sourceRoot":"","sources":["../src/doc-blocks.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAQlD,CAAA;AAWD,8EAA8E;AAC9E,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAkDD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,MAAM,KAAG,SAAS,QAAQ,EAKrE,CAAA"}

package/dist/doc-blocks.js

@@ -0,0 +1,75 @@
+// Orphaned documenting comments: a `/** ... */` block whose next non-blank line opens ANOTHER such
+// block, so the first documents nothing and the symbol it was written for carries no doc at all.
+//
+// This cannot be an eslint-plugin-jsdoc rule, and the reason is structural rather than a gap in that
+// plugin. Every rule it ships visits the block ATTACHED to a syntax node, and an orphan is attached to
+// nothing: the parser hands a declaration only the LAST block comment before it and discards the
+// earlier ones as leading trivia. The defect is invisible to the one analyzer that exists for
+// documenting comments, which is why it is a text rule here - the text is the only place it is still
+// visible.
+//
+// It is a real class rather than a hypothetical. Four instances were found in this repository the
+// first time anything looked, each one a doc that had been moved above the wrong symbol and left
+// there, and each one carried the description of a symbol that was then undocumented.
+// Extensions whose comment syntax this rule understands. A stylesheet shares the delimiters but has
+// no JSDoc, so two adjacent blocks there are two comments rather than one orphan - which is why this
+// list is narrower than CODE_EXTENSIONS.
+export const DOCUMENTED_EXTENSIONS = [
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+    '.js',
+    '.mjs',
+    '.cjs',
+];
+const DOC_OPEN = '/**';
+const BLOCK_CLOSE = '*/';
+/** The sentinel for "no block is currently open", distinguishable from every 1-based line number. */
+const NO_OPEN_BLOCK = -1;
+/** Array indices are 0-based and reported line numbers are 1-based. */
+const FIRST_LINE = 1;
+const EMPTY_SCAN = { open: NO_OPEN_BLOCK, blocks: [] };
+// A block that opens and closes on one line, which is the shape most one-sentence docs take. The
+// search starts past the opening marker so its own trailing asterisk cannot be read as the close.
+const endsOnOpeningLine = (trimmed) => trimmed.slice(DOC_OPEN.length).includes(BLOCK_CLOSE);
+const afterOpenLine = (state, trimmed, line) => {
+    if (!trimmed.startsWith(DOC_OPEN)) {
+        return state;
+    }
+    return endsOnOpeningLine(trimmed)
+        ? { open: NO_OPEN_BLOCK, blocks: [...state.blocks, { line, endLine: line }] }
+        : { open: line, blocks: state.blocks };
+};
+const afterBodyLine = (state, trimmed, line) => trimmed.includes(BLOCK_CLOSE)
+    ? { open: NO_OPEN_BLOCK, blocks: [...state.blocks, { line: state.open, endLine: line }] }
+    : state;
+// Every documenting comment in the file, in reading order. Only blocks opened by `/**` at the start of
+// a line are collected: a `/**` inside a string or trailing another statement is not a doc block, and
+// treating it as one would report a defect at a position that holds none.
+const docBlocks = (lines) => lines.reduce((state, raw, index) => {
+    const trimmed = raw.trim();
+    const line = index + FIRST_LINE;
+    return state.open === NO_OPEN_BLOCK
+        ? afterOpenLine(state, trimmed, line)
+        : afterBodyLine(state, trimmed, line);
+}, EMPTY_SCAN).blocks;
+// Blank lines are skipped rather than treated as separation. A doc block separated from the next doc
+// block by an empty line is orphaned exactly as tightly as one that is not: what makes it an orphan is
+// that no declaration follows it, and whitespace is not a declaration.
+const opensAnotherBlock = (lines, endLine) => {
+    const next = lines
+        .slice(endLine)
+        .find((line) => line.trim().length > 0);
+    return (next ?? '').trimStart().startsWith(DOC_OPEN);
+};
+/**
+ * Find every documenting comment that is followed by another one rather than by what it documents.
+ * @param text the file contents, with lines separated by "\n" or "\r\n".
+ * @returns one entry per orphaned block, in reading order.
+ */
+export const findOrphanedDocBlocks = (text) => {
+    const lines = text.replaceAll('\r\n', '\n').split('\n');
+    return docBlocks(lines).filter((block) => opensAnotherBlock(lines, block.endLine));
+};
+//# sourceMappingURL=doc-blocks.js.map