@seanmars/tospec 0.19.0-beta.7 → 0.20.0

package/dist/core/validation/types.d.ts

@@ -5,6 +5,16 @@ export interface ValidationIssue {
     message: string;
     line?: number;
     column?: number;
+    /**
+     * Background explaining the rule rather than this occurrence of it — why the
+     * check is a warning, what it cannot see, what to do in general.
+     *
+     * Separate from the per-occurrence `message` because it is identical every
+     * time the rule fires; inlined, it repeats once per occurrence and buries the
+     * names that differ. `createReport` hoists these into
+     * `ValidationReport.notes`, deduplicated, and clears them from the issues.
+     */
+    note?: string;
 }
 export interface ValidationReport {
     valid: boolean;
@@ -14,5 +24,13 @@ export interface ValidationReport {
         warnings: number;
         info: number;
     };
+    /** Distinct `ValidationIssue.note` values, each carried once. */
+    notes?: string[];
 }
+/**
+ * Severity symbol for human output. Shared so no two surfaces show different
+ * glyphs for one level; the line formats around it differ on purpose
+ * (`validate` prints the level, `archive` does not), so only this is common.
+ */
+export declare function issueSymbol(level: ValidationLevel | string): string;
 //# sourceMappingURL=types.d.ts.map

package/dist/core/validation/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/validation/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/validation/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,CAInE"}

package/dist/core/validation/types.js

@@ -1,2 +1,13 @@
-export {};
+/**
+ * Severity symbol for human output. Shared so no two surfaces show different
+ * glyphs for one level; the line formats around it differ on purpose
+ * (`validate` prints the level, `archive` does not), so only this is common.
+ */
+export function issueSymbol(level) {
+    if (level === 'ERROR')
+        return '✗';
+    if (level === 'WARNING')
+        return '⚠';
+    return 'ℹ';
+}
 //# sourceMappingURL=types.js.map

package/dist/core/validation/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/validation/types.ts"],"names":[],"mappings":""}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/validation/types.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAA+B;IACzD,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,GAAG,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IACpC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/core/validation/validator.d.ts

@@ -3,102 +3,82 @@ export declare class Validator {
     private strictMode;
     constructor(strictMode?: boolean);
     validateSpec(filePath: string): Promise<ValidationReport>;
-    /**
-     * Validate spec content from a string (used for pre-write validation of rebuilt specs)
-     */
     validateSpecContent(specName: string, content: string): Promise<ValidationReport>;
-    validateChange(filePath: string): Promise<ValidationReport>;
     /**
-     * Validate delta-formatted spec files under a change directory.
-     * Enforces:
-     * - At least one delta across all files
-     * - ADDED/MODIFIED: each requirement has SHALL/MUST and at least one scenario
-     * - REMOVED: names only; no scenario/description required
-     * - RENAMED: pairs well-formed
-     * - No duplicates within sections; no cross-section conflicts per spec
-     * - MODIFIED: no scenario the current main spec still has is dropped
+     * Validate delta-formatted spec files under a change directory: at least one
+     * delta overall, ADDED/MODIFIED requirements carrying SHALL/MUST and a
+     * scenario, well-formed REMOVED (names only) and RENAMED (FROM:/TO: pairs)
+     * entries, no duplicate or cross-section names, and no scenario the current
+     * main spec still has dropped by a MODIFIED.
      *
-     * `mainSpecsDir` enables that last rule; without it the scenario-loss check is
-     * skipped, because there is nothing to compare against. Callers that have the
-     * project root should always pass it — archive refuses these deltas either
-     * way, and the check only decides whether the user learns now or at archive
-     * time.
-     */
-    /**
-     * `archivePreflight` is opt-out because the dry run below is worth its cost to
-     * exactly one caller. It rebuilds every updated spec — re-reading and
-     * re-parsing the delta and the whole main spec per capability — to report,
-     * at INFO, what the merge would refuse. For `tospec validate` that is the
-     * point: the author learns before they try. For `archive` it is pure
-     * duplication, because archive runs the real merge moments later and already
-     * turns the same precondition into `archive_spec_update_failed` with a
-     * non-zero exit, which the INFO never had the level to do.
+     * `mainSpecsDir` enables that last rule; without it there is nothing to
+     * compare against, so it is skipped. Archive refuses such deltas either way.
+     *
+     * `archivePreflight` is opt-out because the dry run rebuilds every updated
+     * spec. For `tospec validate` that is the point; for `archive` it is
+     * duplication, since the real merge follows moments later.
      */
     validateChangeDeltaSpecs(changeDir: string, mainSpecsDir?: string, options?: {
         archivePreflight?: boolean;
     }): Promise<ValidationReport>;
     private convertZodErrors;
     private applySpecRules;
-    private applyChangeRules;
     private enrichTopLevelError;
     private createReport;
     private extractRequirementText;
-    private containsShallOrMust;
     /**
-     * Build an error message for a requirement block whose body lacks SHALL/MUST.
-     *
-     * When the SHALL/MUST keyword already appears in the requirement header (e.g.
-     * `### Requirement: The system SHALL ...`) the original generic error
-     * ("must contain SHALL or MUST") is confusing because the keyword is visibly
-     * present in the spec. Per the Tospec conventions the keyword has to live
-     * on the requirement body line (the line right after the header), so we point
-     * the author at that exact fix when the keyword is found in the header only.
+     * When the keyword already appears in the header (`### Requirement: The system
+     * SHALL ...`) the generic "must contain SHALL or MUST" reads as wrong, since
+     * the keyword is visibly there. The convention puts it on the body line, so
+     * point the author at that exact fix instead.
      */
     private buildMissingShallOrMustMessage;
+    /**
+     * The main spec's two Purpose rules, applied to a delta that is about to
+     * create that main spec. Placeholder before brevity, as on the spec path.
+     *
+     * `mainSpecsDir` absent means new capabilities cannot be told from existing
+     * ones, so nothing is reported.
+     */
+    private collectDeltaPurposeIssues;
     /**
      * Scenarios a MODIFIED block would delete from the current main spec.
      *
      * A MODIFIED replaces the whole requirement, so a scenario the block omits is
-     * lost. `specs-apply` already refuses to apply such a block, but only at
-     * archive time — so a change could validate clean, be implemented and
-     * reviewed, and fail days later at the most expensive possible moment. Both
-     * sides now call `findMissingScenarios`, so validate reports exactly what
-     * archive refuses.
+     * lost. `specs-apply` refuses such a block too, but only at archive time. Both
+     * sides call `findMissingScenarios`, so validate reports what archive refuses.
      *
-     * Deliberately silent in two cases, because archive gates them separately and
-     * a warning here would be a false alarm:
-     * - the main spec file does not exist yet (the capability is new)
-     * - the requirement header is absent from it (a MODIFIED written against a
-     *   sister change still in flight)
+     * Silent when the main spec does not exist yet (new capability) or lacks the
+     * requirement header (a MODIFIED written against a sister change still in
+     * flight): archive gates both separately.
      */
     private collectDroppedScenarioIssues;
     /**
-     * Dry-run the merge and report what it would refuse.
+     * Dry-run the merge and report what it would refuse, plus the one thing it
+     * would accept while doing nothing.
      *
      * Reusing the merge builder rather than restating its preconditions is the
-     * whole point: several of them deliberately read a missing target as
-     * already-synced rather than as a failure, and a second copy of those rules
-     * would be free to drift — which shows up as validate and archive disagreeing,
-     * the one thing this check exists to prevent.
+     * point: a second copy would be free to drift, which shows up as validate and
+     * archive disagreeing.
      *
-     * INFO leaves the verdict alone. A MODIFIED whose target is missing is also
-     * what a change modifying a sibling's unarchived requirement looks like, and
-     * that is valid today; what is missing is the information, not the verdict.
+     * WARNING, not ERROR or INFO. ERROR is wrong because a MODIFIED whose target
+     * is missing is also what a change modifying a sibling's unarchived
+     * requirement looks like. INFO was wrong because `--strict` ignores it, so the
+     * pre-archive gate waved through changes archive would refuse.
+     * tospec/decisions/20260916_154000-archive-dry-run-findings-are-warnings.md
      */
     private findArchiveBlockers;
     /**
-     * Scenario-quality rules for a delta requirement block (report 2.1): only
-     * `#### Scenario:` headers count as scenarios, each scenario body must
-     * contain WHEN and THEN (uppercase, per the spec convention), and stray
-     * level-4 headers get a WARNING so authors know they were not counted.
+     * Scenario-quality rules for a delta requirement block: only `#### Scenario:`
+     * headers count, each scenario body must contain uppercase WHEN and THEN, and
+     * a stray level-4 header gets a WARNING so the author knows it was not counted.
      */
     private collectScenarioIssues;
     /**
      * RENAMED/REMOVED have their own grammar (FROM:/TO: pairs; name bullets with
-     * Reason/Migration), not the `### Requirement:` block ADDED/MODIFIED use.
-     * Pointing a RENAMED/REMOVED author at "add a ### Requirement: block" sends
-     * them to a fix that does not work — see
-     * tospec/changes/delta-syntax-diagnostics-misleading/task.md.
+     * Reason/Migration), not the `### Requirement:` block ADDED/MODIFIED use, so
+     * "add a ### Requirement: block" would send their authors to a fix that does
+     * not work.
      */
     private formatEmptySectionMessage;
 }

package/dist/core/validation/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/core/validation/validator.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAoC,MAAM,YAAY,CAAC;AAqBhF,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAU;IAE5B,YAAY,UAAU,GAAE,OAAe,EAEtC;IAEK,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAe9D;IAED;;OAEG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgBtF;IAEK,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6BhE;IAED;;;;;;;;;;;;;;;OAeG;IACH;;;;;;;;;OASG;IACG,wBAAwB,CAC5B,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAO,GAC3C,OAAO,CAAC,gBAAgB,CAAC,CAkV3B;IAED,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,cAAc;IA6FtB,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,sBAAsB;IAU9B,OAAO,CAAC,mBAAmB;IAI3B;;;;;;;;;OASG;IACH,OAAO,CAAC,8BAA8B;IAQtC;;;;;;;;;;;;;;;OAeG;YACW,4BAA4B;IAqD1C;;;;;;;;;;;;OAYG;YACW,mBAAmB;IA4DjC;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;IA2C7B;;;;;;OAMG;IACH,OAAO,CAAC,yBAAyB;CAalC"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/core/validation/validator.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAoC,MAAM,YAAY,CAAC;AAoFhF,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAU;IAE5B,YAAY,UAAU,GAAE,OAAe,EAEtC;IAEK,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAc9D;IAEK,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgBtF;IAED;;;;;;;;;;;;;OAaG;IACG,wBAAwB,CAC5B,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAO,GAC3C,OAAO,CAAC,gBAAgB,CAAC,CA4Z3B;IAED,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,cAAc;IAgFtB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,sBAAsB;IAQ9B;;;;;OAKG;IACH,OAAO,CAAC,8BAA8B;IAuBtC;;;;;;OAMG;YACW,yBAAyB;IA4CvC;;;;;;;;;;OAUG;YACW,4BAA4B;IA8I1C;;;;;;;;;;;;;OAaG;YACW,mBAAmB;IAyEjC;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAqE7B;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;CAalC"}