@primmel/primmel 1.3.2 → 1.4.0

package/dist/src/model-diff.d.ts

@@ -0,0 +1,198 @@
+import type Standard from './types/Standard';
+import type { CoverageLevel } from './types/MapProfile';
+import { type MappingRecord, type ProcessTreeNode } from './mapping-coverage';
+export type TierName = 'foundations' | 'primary' | 'secondary' | 'tertiary' | 'cross-cutting';
+export declare const TIER_ORDER: TierName[];
+/**
+ * The tier of every diffable Standard collection (chapter 1's table):
+ * foundations = what everything references (vocabulary, parties, units,
+ * registers); primary = the subject and its aspects (the instrument
+ * chain, attributes, behaviors, conditions, instances, duals, artifacts);
+ * secondary = models ANCHORED to primary aspect paths (requirements,
+ * tests, forms, verdict quantities, tables of limits); tertiary =
+ * execution and judgment (processes, entities, registries, state
+ * machines, approvals, monitors, passports); cross-cutting = annotation
+ * and traceability furniture (notes, invariants, test sequences,
+ * formulas-used traces, links).
+ *
+ * mapProfiles are deliberately ABSENT: mappings are not tiered elements
+ * — the mapping diff owns them (pairs + coverage delta).
+ */
+export declare const TIER_BY_FIELD: Record<string, TierName>;
+/**
+ * Deterministic serialization: sorted object keys, arrays in declared
+ * order (within-element order is significant — procedure steps and
+ * applicability entries are meaningful sequences), `_`-prefixed keys
+ * (resolver internals) dropped, shared resolved references guarded
+ * against cycles.
+ */
+export declare function canonical(value: unknown): string;
+/** A source ref normalized for cross-edition comparison. */
+export interface NormalizedSourceRef {
+    /** Doc URN with the trailing edition segment stripped. */
+    basis: string;
+    /** The stripped edition (e.g. "2021"; '' when the URN carries none). */
+    edition: string;
+    clause: string;
+    fragment: string;
+}
+/**
+ * Normalize a source ref onto its doc basis: `urn:oiml:pub:r:60-2:2021`
+ * → basis `urn:oiml:pub:r:60-2`, edition `2021`. A `#fragment` suffix on
+ * the doc moves into the fragment slot. The trailing segment counts as an
+ * edition when it is all digits (the OIML URN convention
+ * `urn:oiml:pub:<doc>:<year>`); other URNs compare whole.
+ */
+export declare function normalizeSourceRef(doc: string, clause: string, fragment?: string): NormalizedSourceRef;
+/** One diffable model element, normalized out of its Standard collection. */
+export interface DiffElement {
+    /** `${field}:${id}` — the primary key (ids alone may collide across kinds). */
+    key: string;
+    id: string;
+    /** The Standard collection field (requirements, conformanceTests, …). */
+    kind: string;
+    tier: TierName;
+    /** Aspect name → canonical content (only aspects with content present). */
+    aspects: Record<string, string>;
+    /** Edition-normalized provenance edges (empty when the element cites none). */
+    provenance: NormalizedSourceRef[];
+}
+/**
+ * The id-keyed element index of a Standard — the diff's normalized input.
+ * Renaming a file or reordering declarations leaves the index untouched.
+ * A duplicate `kind:id` key is a DATA ERROR (the duplicate-id linter owns
+ * it): the last declaration wins the slot, so a diff over an unlinted
+ * package with duplicates under-reports. Keys of overwritten duplicates
+ * are collected into `duplicates` when given — the caller surfaces them
+ * as warnings (diffStandards does).
+ */
+export declare function elementIndex(standard: Standard, duplicates?: string[]): Map<string, DiffElement>;
+export interface DiffEntry {
+    key: string;
+    id: string;
+    kind: string;
+    tier: TierName;
+}
+/** A shared id whose content differs — with the classified aspects. */
+export interface ChangeEntry extends DiffEntry {
+    aspects: string[];
+}
+/**
+ * A shared id whose ONLY change is the anchor — re-anchored (§13.2).
+ * from/to are the canonical ANCHOR aspect (location fields only), never
+ * the whole binding surface.
+ */
+export interface MoveEntry extends DiffEntry {
+    from: string;
+    to: string;
+}
+/** A mapping pair present in both versions with changed metadata. */
+export interface MappingPairChange {
+    source: string;
+    sourceModel: string;
+    target: string;
+    /** Which of description / justification changed. */
+    aspects: string[];
+}
+/** A computed coverage-level change for one reference component. */
+export interface CoverageDeltaEntry {
+    namespace: string;
+    component: string;
+    from: CoverageLevel | 'absent';
+    to: CoverageLevel | 'absent';
+}
+/** The mapping diff: pairs + the computed coverage delta (§13.2). */
+export interface MappingDiff {
+    added: MappingRecord[];
+    removed: MappingRecord[];
+    changed: MappingPairChange[];
+    coverageDelta: CoverageDeltaEntry[];
+    /** Target namespaces with no process tree on either side (delta silent). */
+    namespacesSkipped: string[];
+}
+export type ClauseDriftKind = 'renumbered' | 'recited' | 'decited';
+/** One clause-drift table row, aggregated across the citing elements. */
+export interface ClauseDriftRow {
+    /** Doc basis (edition-stripped URN) both editions share. */
+    doc: string;
+    /** The clause the old edition cited ('' for a recited clause). */
+    from: string;
+    /** The clause the new edition cites ('' for a de-cited clause). */
+    to: string;
+    kind: ClauseDriftKind;
+    /**
+     * Clause-text comparison across the editions (sources-prd payloads):
+     * 'same' (a pure renumbering), 'differed' (renumbered AND reworded),
+     * 'unavailable' (payloads missing on either side — structural only).
+     */
+    text: 'same' | 'differed' | 'unavailable';
+    citedBy: DiffEntry[];
+}
+export interface TierTally {
+    added: number;
+    removed: number;
+    changed: number;
+    moved: number;
+    unchanged: number;
+}
+export interface ModelDiff {
+    aLabel: string;
+    bLabel: string;
+    /** True when both sides are the same package id at different versions. */
+    editionComparison: boolean;
+    aVersion: string;
+    bVersion: string;
+    added: DiffEntry[];
+    removed: DiffEntry[];
+    changed: ChangeEntry[];
+    moved: MoveEntry[];
+    unchanged: number;
+    byTier: Record<TierName, TierTally>;
+    mappings: MappingDiff;
+    clauseDrift: ClauseDriftRow[];
+    /**
+     * Data-quality warnings surfaced while indexing (duplicate kind:id
+     * keys — the last declaration wins the slot). A warning is not a model
+     * change: it never affects `empty`.
+     */
+    warnings: string[];
+    empty: boolean;
+}
+/**
+ * Clause → concatenated sentence text, keyed by doc basis — the
+ * rewording detector's input (built from `<part>.sentences.json`
+ * payloads by package-diff.ts).
+ */
+export type ClauseTextIndex = Map<string, string>;
+export declare function clauseTextKey(basis: string, clause: string): string;
+export interface ModelDiffOptions {
+    aLabel?: string;
+    bLabel?: string;
+    /** Mapping records overriding collectMappings() (e.g. with .prm files). */
+    mappingsA?: MappingRecord[];
+    mappingsB?: MappingRecord[];
+    /**
+     * Reference process trees per target namespace for the coverage delta;
+     * falls back to each side's own `Namespace#…` alias forest (the C23
+     * fallback), then to silence (namespacesSkipped).
+     */
+    references?: Record<string, Standard | ProcessTreeNode[]>;
+    /** Clause-text indexes for the rewording classification. */
+    sentencesA?: ClauseTextIndex;
+    sentencesB?: ClauseTextIndex;
+}
+/**
+ * The structural model diff between two loaded Standards (§13.2). `a` is
+ * the OLD state, `b` the NEW one (edition comparison reads 2017 → 2021).
+ */
+export declare function diffStandards(a: Standard, b: Standard, options?: ModelDiffOptions): ModelDiff;
+/**
+ * The human-readable change summary between two package states — the
+ * edition-comparison report (§13.3.1): tier-annotated tallies, the
+ * added/removed/changed/moved lists with classified aspects, the mapping
+ * diff with its computed coverage delta, and the clause-drift table
+ * (renumbered clauses, re-cited provisions) — the R 60:2017→2021
+ * renumbering made machine-visible.
+ */
+export declare function formatDiffReport(diff: ModelDiff): string;
+//# sourceMappingURL=model-diff.d.ts.map

package/dist/src/model-diff.d.ts.map

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