@principal-ai/subsystems-core 0.48.2 → 0.49.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/types/subsystem-model.d.ts +35 -10
- package/dist/types/subsystem-model.d.ts.map +1 -1
- package/dist/types/subsystem-model.js.map +1 -1
- package/dist/validation.d.ts.map +1 -1
- package/dist/validation.js +23 -0
- package/dist/validation.js.map +1 -1
- package/package.json +1 -1
- package/schemas/subsystem-model.schema.json +19 -27
- package/src/types/subsystem-model.test.ts +12 -2
- package/src/types/subsystem-model.ts +35 -10
- package/src/validation.test.ts +67 -4
- package/src/validation.ts +34 -0
|
@@ -77,13 +77,29 @@ export interface SubsystemDeclToken {
|
|
|
77
77
|
/** Optional foreground when pre-tokenized for a theme. */
|
|
78
78
|
color?: string;
|
|
79
79
|
}
|
|
80
|
-
/**
|
|
81
|
-
|
|
82
|
-
|
|
80
|
+
/**
|
|
81
|
+
* A content-addressed range of source — the model's identity primitive.
|
|
82
|
+
*
|
|
83
|
+
* A span is `startLine` + `endLine` + the hash of the normalized content
|
|
84
|
+
* across that range. Every claim is *anchored* to a span: a component's
|
|
85
|
+
* construct declaration (`declarationSpan`) and a trail step's runtime seam
|
|
86
|
+
* (`span`) are the same shape. `file` / `purl` live on the owner, so a span is
|
|
87
|
+
* a pure range + fingerprint.
|
|
88
|
+
*
|
|
89
|
+
* The hash is the identity: if live content re-hashes to `contentHash`, the
|
|
90
|
+
* anchored code is byte-identical, which is what lets verification reason about
|
|
91
|
+
* constructs rather than line changes.
|
|
92
|
+
*/
|
|
93
|
+
export interface SubsystemSourceSpan {
|
|
94
|
+
/** 1-based first line of the construct/seam within the owner's `file`. */
|
|
83
95
|
startLine: number;
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
96
|
+
/** 1-based last line, inclusive. Always `>= startLine`. */
|
|
97
|
+
endLine: number;
|
|
98
|
+
/**
|
|
99
|
+
* SHA-256 of the normalized content across `[startLine, endLine]`, truncated
|
|
100
|
+
* to 32 hex chars. Produced by `hashContentRange`.
|
|
101
|
+
*/
|
|
102
|
+
contentHash: string;
|
|
87
103
|
}
|
|
88
104
|
export interface SubsystemParamInfo {
|
|
89
105
|
name?: string;
|
|
@@ -316,8 +332,12 @@ export interface SubsystemComponent {
|
|
|
316
332
|
*/
|
|
317
333
|
declarationProvenance?: SubsystemDeclarationProvenance;
|
|
318
334
|
tokens?: SubsystemDeclToken[];
|
|
319
|
-
/**
|
|
320
|
-
|
|
335
|
+
/**
|
|
336
|
+
* The construct's source span (start/end/content hash) — its anchored
|
|
337
|
+
* identity. Distinct from `declaration`, which is the structured shape.
|
|
338
|
+
* Usually captured by verify tooling, not hand-authored.
|
|
339
|
+
*/
|
|
340
|
+
declarationSpan?: SubsystemSourceSpan;
|
|
321
341
|
}
|
|
322
342
|
/**
|
|
323
343
|
* Derived / display graph edge used by renderers. Built from trail
|
|
@@ -337,8 +357,13 @@ export interface SubsystemTrailStep {
|
|
|
337
357
|
/** Runtime seam label (Set B). */
|
|
338
358
|
mechanism: SubsystemTrailMechanism;
|
|
339
359
|
file: string;
|
|
340
|
-
/**
|
|
341
|
-
|
|
360
|
+
/**
|
|
361
|
+
* The seam's source span — the call-site range and its content hash. The
|
|
362
|
+
* trail-step counterpart of a component's `declarationSpan`, captured by
|
|
363
|
+
* verify tooling from the call site. `file` + `symbol` locate the frame;
|
|
364
|
+
* absent until verification anchors it.
|
|
365
|
+
*/
|
|
366
|
+
span?: SubsystemSourceSpan;
|
|
342
367
|
/**
|
|
343
368
|
* File-anchored purl of the seam site (e.g.
|
|
344
369
|
* `pkg:github/owner/name#path/to/file.ts`), mirroring component `purl`.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"subsystem-model.d.ts","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;0CAE0C;AAC1C,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,UAAU,GACV,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,MAAM,GACN,OAAO,GACP,UAAU,GACV,eAAe,CAAC;AAEpB,oEAAoE;AACpE,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAExC;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAC/B,OAAO,GACP,MAAM,GACN,OAAO,GACP,UAAU,GACV,QAAQ,GACR,OAAO,GACP,SAAS,GACT,gBAAgB,CAAC;AAErB;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,GAAG,UAAU,GAAG,UAAU,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,MAAM,GACN,QAAQ,GACR,MAAM,GACN,aAAa,GACb,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,sBAAsB,CAAC;IAC7B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED
|
|
1
|
+
{"version":3,"file":"subsystem-model.d.ts","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;0CAE0C;AAC1C,MAAM,MAAM,kBAAkB,GAC1B,OAAO,GACP,UAAU,GACV,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,MAAM,GACN,OAAO,GACP,UAAU,GACV,eAAe,CAAC;AAEpB,oEAAoE;AACpE,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAExC;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAC/B,OAAO,GACP,MAAM,GACN,OAAO,GACP,UAAU,GACV,QAAQ,GACR,OAAO,GACP,SAAS,GACT,gBAAgB,CAAC;AAErB;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,8BAA8B,GAAG,UAAU,GAAG,UAAU,CAAC;AAErE;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,sBAAsB,GAC9B,SAAS,GACT,MAAM,GACN,QAAQ,GACR,MAAM,GACN,aAAa,GACb,QAAQ,GACR,SAAS,CAAC;AAEd,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,sBAAsB,CAAC;IAC7B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,sBAAsB,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,sBAAsB,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,UAAU,EAAE,qBAAqB,EAAE,CAAC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACxC;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,0DAA0D;AAC1D,MAAM,WAAW,yBAAyB;IACxC,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,qBAAqB,EAAE,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACpC,gDAAgD;IAChD,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC,mDAAmD;IACnD,WAAW,CAAC,EAAE,uBAAuB,EAAE,CAAC;IACxC,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,8BAA8B,EAAE,CAAC;CAC/C;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,OAAO,CAAC;IACd;;;yBAGqB;IACrB,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IACzC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;gCAC4B;IAC5B,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,UAAU,EAAE,qBAAqB,EAAE,CAAC;CACrC;AAED,4EAA4E;AAC5E,MAAM,WAAW,8BAA8B;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,gCAAgC;IAC/C,IAAI,EAAE,eAAe,CAAC;IACtB,UAAU,EAAE,8BAA8B,EAAE,CAAC;CAC9C;AAED,mDAAmD;AACnD,MAAM,MAAM,6BAA6B,GACrC,yBAAyB,GACzB,4BAA4B,GAC5B,0BAA0B,GAC1B,wBAAwB,GACxB,4BAA4B,GAC5B,yBAAyB,GACzB,gCAAgC,CAAC;AAErC,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,kBAAkB,CAAC;IAC9B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,0GAA0G;IAC1G,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,sBAAsB,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;OAGG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B;;;OAGG;IACH,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,WAAW,CAAC,EAAE,6BAA6B,CAAC;IAC5C;;;OAGG;IACH,qBAAqB,CAAC,EAAE,8BAA8B,CAAC;IACvD,MAAM,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,mBAAmB,CAAC;CACvC;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,sBAAsB,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,SAAS,EAAE,uBAAuB,CAAC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,kBAAkB,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC,iDAAiD;IACjD,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;IAC1B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAC9C;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAChD;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAuB,SAAQ,sBAAsB;IACpE,wCAAwC;IACxC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAOxF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,sBAAsB,GAC1B,sBAAsB,CAWxB;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,sBAAsB,GAChC,MAAM,CAER;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAA;CAAE,GAC1D,oBAAoB,EAAE,CAcxB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAA;CAAE,GAC1D,oBAAoB,EAAE,CAcxB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE;IACpC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAC;CAC3B,GAAG,sBAAsB,EAAE,CAgB3B"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"subsystem-model.js","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;;
|
|
1
|
+
{"version":3,"file":"subsystem-model.js","sourceRoot":"","sources":["../../src/types/subsystem-model.ts"],"names":[],"mappings":"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"}
|
package/dist/validation.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,sBAAsB,
|
|
1
|
+
{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,sBAAsB,EAIvB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,0BAA0B;IACzC,mFAAmF;IACnF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAqDD;;;GAGG;AACH,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,sBAAsB,GAC1B,0BAA0B,EAAE,CAwF9B"}
|
package/dist/validation.js
CHANGED
|
@@ -39,6 +39,23 @@ function isUngrounded(c) {
|
|
|
39
39
|
function mentionsNodeModules(path) {
|
|
40
40
|
return /(^|\/)node_modules(\/|$)/.test(path);
|
|
41
41
|
}
|
|
42
|
+
/**
|
|
43
|
+
* A span's range must be ordered: `endLine >= startLine`. The schema enforces
|
|
44
|
+
* that each line is a positive integer but cannot compare two fields, so the
|
|
45
|
+
* ordering rule lives here. `owner` prefixes the message (e.g.
|
|
46
|
+
* `component "save"`).
|
|
47
|
+
*/
|
|
48
|
+
function spanRangeProblem(span, path, owner) {
|
|
49
|
+
if (!span)
|
|
50
|
+
return null;
|
|
51
|
+
if (span.endLine < span.startLine) {
|
|
52
|
+
return {
|
|
53
|
+
path,
|
|
54
|
+
message: `${owner}: span endLine ${span.endLine} precedes startLine ${span.startLine} — a span range must be ordered (endLine >= startLine).`,
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
return null;
|
|
58
|
+
}
|
|
42
59
|
/**
|
|
43
60
|
* Validate the cross-field rules of a subsystem model document. Returns an
|
|
44
61
|
* empty array when the document is consistent.
|
|
@@ -79,6 +96,9 @@ function validateSubsystemModelCrossField(doc) {
|
|
|
79
96
|
message: `component ${JSON.stringify(c.alias)}: file ${JSON.stringify(file)} points into node_modules — installed artifacts are not part of the repo and cannot be verified. Model the dependency as construct "external" with purl "pkg:npm/<package>" and no file, or anchor the claim to the package's real source.`,
|
|
80
97
|
});
|
|
81
98
|
}
|
|
99
|
+
const spanProblem = spanRangeProblem(c.declarationSpan, `/components/${i}/declarationSpan`, `component ${JSON.stringify(c.alias)}`);
|
|
100
|
+
if (spanProblem)
|
|
101
|
+
problems.push(spanProblem);
|
|
82
102
|
});
|
|
83
103
|
trails.forEach((w, ti) => {
|
|
84
104
|
(w.steps ?? []).forEach((step, si) => {
|
|
@@ -112,6 +132,9 @@ function validateSubsystemModelCrossField(doc) {
|
|
|
112
132
|
message: `trail ${JSON.stringify(w.id)}: step ${si} file ${JSON.stringify(step.file)} points into node_modules — anchor the seam at the call site inside the repo instead.`,
|
|
113
133
|
});
|
|
114
134
|
}
|
|
135
|
+
const spanProblem = spanRangeProblem(step.span, `/trails/${ti}/steps/${si}/span`, `trail ${JSON.stringify(w.id)}: step ${si}`);
|
|
136
|
+
if (spanProblem)
|
|
137
|
+
problems.push(spanProblem);
|
|
115
138
|
});
|
|
116
139
|
});
|
|
117
140
|
return problems;
|
package/dist/validation.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;
|
|
1
|
+
{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
},
|
|
33
33
|
"trails": {
|
|
34
34
|
"type": "array",
|
|
35
|
-
"description": "Ordered runtime trails (one per named behavior). Each step names from/to/mechanism and the concrete file
|
|
35
|
+
"description": "Ordered runtime trails (one per named behavior). Each step names from/to/mechanism and the concrete file where that seam fires; the seam's source span is captured by verification.",
|
|
36
36
|
"items": {
|
|
37
37
|
"$ref": "#/$defs/trail"
|
|
38
38
|
}
|
|
@@ -231,9 +231,9 @@
|
|
|
231
231
|
"$ref": "#/$defs/declToken"
|
|
232
232
|
}
|
|
233
233
|
},
|
|
234
|
-
"
|
|
235
|
-
"$ref": "#/$defs/
|
|
236
|
-
"description": "
|
|
234
|
+
"declarationSpan": {
|
|
235
|
+
"$ref": "#/$defs/sourceSpan",
|
|
236
|
+
"description": "The construct's source span (start/end/content hash) — its anchored identity. Usually populated by verify tooling, not hand-authored. Distinct from `declaration`, which is the structured shape."
|
|
237
237
|
}
|
|
238
238
|
}
|
|
239
239
|
},
|
|
@@ -244,7 +244,6 @@
|
|
|
244
244
|
"to",
|
|
245
245
|
"mechanism",
|
|
246
246
|
"file",
|
|
247
|
-
"line",
|
|
248
247
|
"purl",
|
|
249
248
|
"symbol"
|
|
250
249
|
],
|
|
@@ -269,10 +268,9 @@
|
|
|
269
268
|
"pattern": "^(?!.*(^|/)node_modules(/|$)).*$",
|
|
270
269
|
"description": "Repo-root-relative path where the seam fires for this trail."
|
|
271
270
|
},
|
|
272
|
-
"
|
|
273
|
-
"
|
|
274
|
-
"
|
|
275
|
-
"description": "1-based line of the site within `file`."
|
|
271
|
+
"span": {
|
|
272
|
+
"$ref": "#/$defs/sourceSpan",
|
|
273
|
+
"description": "The seam's source span — the call-site range and its content hash. The trail-step counterpart of a component's declarationSpan; captured by verify tooling. `file` + `symbol` locate the frame."
|
|
276
274
|
},
|
|
277
275
|
"purl": {
|
|
278
276
|
"type": "string",
|
|
@@ -352,36 +350,30 @@
|
|
|
352
350
|
}
|
|
353
351
|
}
|
|
354
352
|
},
|
|
355
|
-
"
|
|
353
|
+
"sourceSpan": {
|
|
356
354
|
"type": "object",
|
|
355
|
+
"description": "A content-addressed range of source — the model's identity primitive. startLine/endLine are 1-based inclusive lines within the owner's `file`; contentHash is the hash of the normalized content across that range. `file` / `purl` live on the owner, so a span is a pure range + fingerprint.",
|
|
357
356
|
"required": [
|
|
358
|
-
"file",
|
|
359
357
|
"startLine",
|
|
360
|
-
"
|
|
361
|
-
"
|
|
358
|
+
"endLine",
|
|
359
|
+
"contentHash"
|
|
362
360
|
],
|
|
363
361
|
"additionalProperties": false,
|
|
364
362
|
"properties": {
|
|
365
|
-
"file": {
|
|
366
|
-
"type": "string",
|
|
367
|
-
"description": "Repo-root-relative path (matches component.file)."
|
|
368
|
-
},
|
|
369
363
|
"startLine": {
|
|
370
364
|
"type": "integer",
|
|
371
365
|
"minimum": 1,
|
|
372
|
-
"description": "1-based
|
|
366
|
+
"description": "1-based first line of the construct/seam within the owner's file."
|
|
373
367
|
},
|
|
374
|
-
"
|
|
375
|
-
"type": "
|
|
376
|
-
"
|
|
377
|
-
|
|
378
|
-
"graphifyNodeId": {
|
|
379
|
-
"type": "string",
|
|
380
|
-
"description": "Graphify node id when captured from an exact anchor."
|
|
368
|
+
"endLine": {
|
|
369
|
+
"type": "integer",
|
|
370
|
+
"minimum": 1,
|
|
371
|
+
"description": "1-based last line, inclusive. Always >= startLine (cross-field rule enforced by validation)."
|
|
381
372
|
},
|
|
382
|
-
"
|
|
373
|
+
"contentHash": {
|
|
383
374
|
"type": "string",
|
|
384
|
-
"
|
|
375
|
+
"minLength": 1,
|
|
376
|
+
"description": "SHA-256 of the normalized content across [startLine, endLine], truncated to 32 hex chars. The span's identity."
|
|
385
377
|
}
|
|
386
378
|
}
|
|
387
379
|
},
|
|
@@ -46,8 +46,18 @@ describe("subsystem-model schema", () => {
|
|
|
46
46
|
expect(schema.properties.verifiedAtCommits).toBeDefined();
|
|
47
47
|
});
|
|
48
48
|
|
|
49
|
-
test("
|
|
50
|
-
|
|
49
|
+
test("declares a content-addressed source span", () => {
|
|
50
|
+
// The identity primitive: start + end + content hash. Replaces the old
|
|
51
|
+
// start-line-only `declarationRef`.
|
|
52
|
+
expect(schema.$defs.sourceSpan?.properties?.startLine).toBeDefined();
|
|
53
|
+
expect(schema.$defs.sourceSpan?.properties?.endLine).toBeDefined();
|
|
54
|
+
expect(schema.$defs.sourceSpan?.properties?.contentHash).toBeDefined();
|
|
55
|
+
expect(schema.$defs.declarationRef).toBeUndefined();
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
test("trail steps carry a span, not a bare line", () => {
|
|
59
|
+
expect(schema.$defs.trailStep?.properties?.span).toBeDefined();
|
|
60
|
+
expect(schema.$defs.trailStep?.properties?.line).toBeUndefined();
|
|
51
61
|
});
|
|
52
62
|
|
|
53
63
|
test("a store declares its own value type", () => {
|
|
@@ -113,13 +113,29 @@ export interface SubsystemDeclToken {
|
|
|
113
113
|
color?: string;
|
|
114
114
|
}
|
|
115
115
|
|
|
116
|
-
/**
|
|
117
|
-
|
|
118
|
-
|
|
116
|
+
/**
|
|
117
|
+
* A content-addressed range of source — the model's identity primitive.
|
|
118
|
+
*
|
|
119
|
+
* A span is `startLine` + `endLine` + the hash of the normalized content
|
|
120
|
+
* across that range. Every claim is *anchored* to a span: a component's
|
|
121
|
+
* construct declaration (`declarationSpan`) and a trail step's runtime seam
|
|
122
|
+
* (`span`) are the same shape. `file` / `purl` live on the owner, so a span is
|
|
123
|
+
* a pure range + fingerprint.
|
|
124
|
+
*
|
|
125
|
+
* The hash is the identity: if live content re-hashes to `contentHash`, the
|
|
126
|
+
* anchored code is byte-identical, which is what lets verification reason about
|
|
127
|
+
* constructs rather than line changes.
|
|
128
|
+
*/
|
|
129
|
+
export interface SubsystemSourceSpan {
|
|
130
|
+
/** 1-based first line of the construct/seam within the owner's `file`. */
|
|
119
131
|
startLine: number;
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
132
|
+
/** 1-based last line, inclusive. Always `>= startLine`. */
|
|
133
|
+
endLine: number;
|
|
134
|
+
/**
|
|
135
|
+
* SHA-256 of the normalized content across `[startLine, endLine]`, truncated
|
|
136
|
+
* to 32 hex chars. Produced by `hashContentRange`.
|
|
137
|
+
*/
|
|
138
|
+
contentHash: string;
|
|
123
139
|
}
|
|
124
140
|
|
|
125
141
|
export interface SubsystemParamInfo {
|
|
@@ -376,8 +392,12 @@ export interface SubsystemComponent {
|
|
|
376
392
|
*/
|
|
377
393
|
declarationProvenance?: SubsystemDeclarationProvenance;
|
|
378
394
|
tokens?: SubsystemDeclToken[];
|
|
379
|
-
/**
|
|
380
|
-
|
|
395
|
+
/**
|
|
396
|
+
* The construct's source span (start/end/content hash) — its anchored
|
|
397
|
+
* identity. Distinct from `declaration`, which is the structured shape.
|
|
398
|
+
* Usually captured by verify tooling, not hand-authored.
|
|
399
|
+
*/
|
|
400
|
+
declarationSpan?: SubsystemSourceSpan;
|
|
381
401
|
}
|
|
382
402
|
|
|
383
403
|
/**
|
|
@@ -399,8 +419,13 @@ export interface SubsystemTrailStep {
|
|
|
399
419
|
/** Runtime seam label (Set B). */
|
|
400
420
|
mechanism: SubsystemTrailMechanism;
|
|
401
421
|
file: string;
|
|
402
|
-
/**
|
|
403
|
-
|
|
422
|
+
/**
|
|
423
|
+
* The seam's source span — the call-site range and its content hash. The
|
|
424
|
+
* trail-step counterpart of a component's `declarationSpan`, captured by
|
|
425
|
+
* verify tooling from the call site. `file` + `symbol` locate the frame;
|
|
426
|
+
* absent until verification anchors it.
|
|
427
|
+
*/
|
|
428
|
+
span?: SubsystemSourceSpan;
|
|
404
429
|
/**
|
|
405
430
|
* File-anchored purl of the seam site (e.g.
|
|
406
431
|
* `pkg:github/owner/name#path/to/file.ts`), mirroring component `purl`.
|
package/src/validation.test.ts
CHANGED
|
@@ -32,7 +32,7 @@ describe('validateSubsystemModelCrossField', () => {
|
|
|
32
32
|
{
|
|
33
33
|
id: 'w1',
|
|
34
34
|
title: 'flow',
|
|
35
|
-
steps: [{ from: 'a', to: 'b', mechanism: 'calls', file: 'src/a.ts',
|
|
35
|
+
steps: [{ from: 'a', to: 'b', mechanism: 'calls', file: 'src/a.ts', purl: 'pkg:github/acme/app#src/a.ts', symbol: 'a' }],
|
|
36
36
|
},
|
|
37
37
|
],
|
|
38
38
|
});
|
|
@@ -55,7 +55,7 @@ describe('validateSubsystemModelCrossField', () => {
|
|
|
55
55
|
{
|
|
56
56
|
id: 'w1',
|
|
57
57
|
title: 'flow',
|
|
58
|
-
steps: [{ from: 'ghost', to: 'a', mechanism: 'calls', file: 'src/a.ts',
|
|
58
|
+
steps: [{ from: 'ghost', to: 'a', mechanism: 'calls', file: 'src/a.ts', purl: 'pkg:github/acme/app#src/a.ts', symbol: 'ghost' }],
|
|
59
59
|
},
|
|
60
60
|
],
|
|
61
61
|
}),
|
|
@@ -72,7 +72,7 @@ describe('validateSubsystemModelCrossField', () => {
|
|
|
72
72
|
{
|
|
73
73
|
id: 'w1',
|
|
74
74
|
title: 'flow',
|
|
75
|
-
steps: [{ from: 'a', to: 'a', mechanism: 'calls', file: 'src/a.ts',
|
|
75
|
+
steps: [{ from: 'a', to: 'a', mechanism: 'calls', file: 'src/a.ts', purl: 'pkg:github/acme/app#src/other.ts', symbol: 'a' }],
|
|
76
76
|
},
|
|
77
77
|
],
|
|
78
78
|
}),
|
|
@@ -161,7 +161,6 @@ describe('validateSubsystemModelCrossField', () => {
|
|
|
161
161
|
to: 'a',
|
|
162
162
|
mechanism: 'calls',
|
|
163
163
|
file: 'packages/react/node_modules/@pierre/diffs/dist/index.js',
|
|
164
|
-
line: 1,
|
|
165
164
|
purl: 'pkg:npm/@pierre/diffs#packages/react/node_modules/@pierre/diffs/dist/index.js',
|
|
166
165
|
symbol: 'a',
|
|
167
166
|
},
|
|
@@ -173,4 +172,68 @@ describe('validateSubsystemModelCrossField', () => {
|
|
|
173
172
|
expect(problems).toHaveLength(1);
|
|
174
173
|
expect(problems[0]!.path).toBe('/trails/0/steps/0/file');
|
|
175
174
|
});
|
|
175
|
+
|
|
176
|
+
test('accepts an ordered span on a component and a step', () => {
|
|
177
|
+
expect(
|
|
178
|
+
validateSubsystemModelCrossField(
|
|
179
|
+
doc({
|
|
180
|
+
components: [
|
|
181
|
+
comp('a', {
|
|
182
|
+
declarationSpan: { startLine: 1, endLine: 9, contentHash: 'h' },
|
|
183
|
+
}),
|
|
184
|
+
],
|
|
185
|
+
trails: [
|
|
186
|
+
{
|
|
187
|
+
id: 'w1',
|
|
188
|
+
title: 'flow',
|
|
189
|
+
steps: [
|
|
190
|
+
{
|
|
191
|
+
from: 'a',
|
|
192
|
+
to: 'a',
|
|
193
|
+
mechanism: 'calls',
|
|
194
|
+
file: 'src/a.ts',
|
|
195
|
+
purl: 'pkg:github/acme/app#src/a.ts',
|
|
196
|
+
symbol: 'a',
|
|
197
|
+
span: { startLine: 3, endLine: 3, contentHash: 'h' },
|
|
198
|
+
},
|
|
199
|
+
],
|
|
200
|
+
},
|
|
201
|
+
],
|
|
202
|
+
}),
|
|
203
|
+
),
|
|
204
|
+
).toEqual([]);
|
|
205
|
+
});
|
|
206
|
+
|
|
207
|
+
test('flags a span whose endLine precedes startLine', () => {
|
|
208
|
+
const problems = validateSubsystemModelCrossField(
|
|
209
|
+
doc({
|
|
210
|
+
components: [
|
|
211
|
+
comp('a', {
|
|
212
|
+
declarationSpan: { startLine: 10, endLine: 4, contentHash: 'h' },
|
|
213
|
+
}),
|
|
214
|
+
],
|
|
215
|
+
trails: [
|
|
216
|
+
{
|
|
217
|
+
id: 'w1',
|
|
218
|
+
title: 'flow',
|
|
219
|
+
steps: [
|
|
220
|
+
{
|
|
221
|
+
from: 'a',
|
|
222
|
+
to: 'a',
|
|
223
|
+
mechanism: 'calls',
|
|
224
|
+
file: 'src/a.ts',
|
|
225
|
+
purl: 'pkg:github/acme/app#src/a.ts',
|
|
226
|
+
symbol: 'a',
|
|
227
|
+
span: { startLine: 8, endLine: 2, contentHash: 'h' },
|
|
228
|
+
},
|
|
229
|
+
],
|
|
230
|
+
},
|
|
231
|
+
],
|
|
232
|
+
}),
|
|
233
|
+
);
|
|
234
|
+
expect(problems).toHaveLength(2);
|
|
235
|
+
expect(problems[0]!.path).toBe('/components/0/declarationSpan');
|
|
236
|
+
expect(problems[0]!.message).toContain('precedes startLine');
|
|
237
|
+
expect(problems[1]!.path).toBe('/trails/0/steps/0/span');
|
|
238
|
+
});
|
|
176
239
|
});
|
package/src/validation.ts
CHANGED
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
import type {
|
|
15
15
|
SubsystemModelDocument,
|
|
16
16
|
SubsystemComponent,
|
|
17
|
+
SubsystemSourceSpan,
|
|
17
18
|
SubsystemTrail,
|
|
18
19
|
} from './types/subsystem-model';
|
|
19
20
|
|
|
@@ -53,6 +54,27 @@ function mentionsNodeModules(path: string): boolean {
|
|
|
53
54
|
return /(^|\/)node_modules(\/|$)/.test(path);
|
|
54
55
|
}
|
|
55
56
|
|
|
57
|
+
/**
|
|
58
|
+
* A span's range must be ordered: `endLine >= startLine`. The schema enforces
|
|
59
|
+
* that each line is a positive integer but cannot compare two fields, so the
|
|
60
|
+
* ordering rule lives here. `owner` prefixes the message (e.g.
|
|
61
|
+
* `component "save"`).
|
|
62
|
+
*/
|
|
63
|
+
function spanRangeProblem(
|
|
64
|
+
span: SubsystemSourceSpan | undefined,
|
|
65
|
+
path: string,
|
|
66
|
+
owner: string,
|
|
67
|
+
): SubsystemValidationProblem | null {
|
|
68
|
+
if (!span) return null;
|
|
69
|
+
if (span.endLine < span.startLine) {
|
|
70
|
+
return {
|
|
71
|
+
path,
|
|
72
|
+
message: `${owner}: span endLine ${span.endLine} precedes startLine ${span.startLine} — a span range must be ordered (endLine >= startLine).`,
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
return null;
|
|
76
|
+
}
|
|
77
|
+
|
|
56
78
|
/**
|
|
57
79
|
* Validate the cross-field rules of a subsystem model document. Returns an
|
|
58
80
|
* empty array when the document is consistent.
|
|
@@ -97,6 +119,12 @@ export function validateSubsystemModelCrossField(
|
|
|
97
119
|
message: `component ${JSON.stringify(c.alias)}: file ${JSON.stringify(file)} points into node_modules — installed artifacts are not part of the repo and cannot be verified. Model the dependency as construct "external" with purl "pkg:npm/<package>" and no file, or anchor the claim to the package's real source.`,
|
|
98
120
|
});
|
|
99
121
|
}
|
|
122
|
+
const spanProblem = spanRangeProblem(
|
|
123
|
+
c.declarationSpan,
|
|
124
|
+
`/components/${i}/declarationSpan`,
|
|
125
|
+
`component ${JSON.stringify(c.alias)}`,
|
|
126
|
+
);
|
|
127
|
+
if (spanProblem) problems.push(spanProblem);
|
|
100
128
|
});
|
|
101
129
|
|
|
102
130
|
trails.forEach((w: SubsystemTrail, ti) => {
|
|
@@ -131,6 +159,12 @@ export function validateSubsystemModelCrossField(
|
|
|
131
159
|
message: `trail ${JSON.stringify(w.id)}: step ${si} file ${JSON.stringify(step.file)} points into node_modules — anchor the seam at the call site inside the repo instead.`,
|
|
132
160
|
});
|
|
133
161
|
}
|
|
162
|
+
const spanProblem = spanRangeProblem(
|
|
163
|
+
step.span,
|
|
164
|
+
`/trails/${ti}/steps/${si}/span`,
|
|
165
|
+
`trail ${JSON.stringify(w.id)}: step ${si}`,
|
|
166
|
+
);
|
|
167
|
+
if (spanProblem) problems.push(spanProblem);
|
|
134
168
|
});
|
|
135
169
|
});
|
|
136
170
|
|