truecourse 0.6.0-next.12 → 0.6.0-next.13

package/cli.mjs

@@ -129397,7 +129397,7 @@ function readToolVersion() {
   if (cachedVersion)
     return cachedVersion;
   if (true) {
-    cachedVersion = "0.6.0-next.12";
+    cachedVersion = "0.6.0";
     return cachedVersion;
   }
   try {
@@ -143905,14 +143905,20 @@ Use sensible defaults when the spec doesn't spell them out:
     on-violation {
       status 401
       error-code unauthenticated
-      body ErrorEnvelope:error.envelope.standard
     }
   }
 
-Default \`on-violation\` is **always** status 401, error-code \`unauthenticated\`,
-body \`ErrorEnvelope:error.envelope.standard\` when the spec doesn't specify
-otherwise. Default selector is \`path-glob "/api/**"\` when the spec says "all
-/api/* endpoints" without naming a more specific pattern.
+Default \`on-violation\` is status 401, error-code \`unauthenticated\`. Add a
+\`body ErrorEnvelope:error.envelope.standard\` line ONLY when the spec/corpus
+actually establishes a standard error envelope \u2014 a dedicated errors /
+error-response section, an error-code catalog, or another slice that describes
+the error body shape. When the spec is SILENT about the error response body
+(common for terse auth docs that only state the scheme), OMIT the \`body\` line:
+a \`body\` reference to an envelope nothing defines is a dangling cross-reference
+that fails the validation gate, while an omitted body is faithful. See
+"Error-envelope references must be grounded" below. Default selector is
+\`path-glob "/api/**"\` when the spec says "all /api/* endpoints" without naming a
+more specific pattern.
 
 When a spec describes role-based auth ("admin only", "moderators can \u2026"), produce
 a SEPARATE \`auth-requirement\` with \`required-role <role>\`, identity
@@ -143947,7 +143953,8 @@ is the correct fallback when the slice lacks operation context.
     on-violation {
       status 403
       error-code forbidden
-      body ErrorEnvelope:error.envelope.standard
+      // body ErrorEnvelope:error.envelope.standard only when that envelope is
+      // defined in the corpus \u2014 see "Error-envelope references must be grounded".
     }
   }
 
@@ -144494,6 +144501,37 @@ response as a literal:
 - Only declare a literal \`response 401/403 on \u2026\` when the spec describes the
   response as standalone, NOT delegated to a rule.
 
+# Error-envelope references must be grounded
+
+\`ErrorEnvelope:error.envelope.standard\` is a CROSS-REFERENCE, not a literal \u2014 it
+only resolves if a matching \`error-envelope error.envelope.standard { \u2026 }\`
+artifact exists somewhere in the corpus. Emitting the reference with nothing
+defining it produces a dangling cross-reference that fails the validation gate,
+exactly like referencing an undefined \`Enum:\`. This is the same prime-directive
+rule as enums ("never reference an enum without defining it"), applied to error
+bodies.
+
+The rule applies EVERYWHERE an envelope can appear:
+\`on-violation { \u2026 body ErrorEnvelope:\u2026 }\` on auth-requirements and
+authorization-rules, and \`response \u2026 { body envelope ErrorEnvelope:\u2026 { \u2026 } }\`
+on operations.
+
+- Reference \`ErrorEnvelope:error.envelope.standard\` ONLY when the spec actually
+  establishes a standard error envelope: a dedicated errors / error-response
+  section, an error-code catalog, or prose that names "the standard error
+  envelope". In a multi-doc corpus the defining section may live in ANOTHER
+  slice \u2014 that's fine, just like an \`Enum:\` defined in a sibling slice.
+- When you reference it AND the slice in front of you is the one that describes
+  the envelope, ALSO emit the \`error-envelope error.envelope.standard { \u2026 }\`
+  artifact \u2014 mirroring the described shape; never invent fields the spec does
+  not list.
+- When the spec is SILENT about the error response body \u2014 no error section, no
+  envelope, no error codes \u2014 do NOT emit the reference at all. Omit the \`body\`
+  line from \`on-violation\`; on an operation response use a plain \`body \u2026\` only
+  if the spec gives a shape, otherwise omit it. Faithful under-specification
+  beats a dangling reference: never conjure a standard envelope just to fill the
+  slot.
+
 # Naming conventions for artifact identities
 
 Use these canonical identity formats:
@@ -148874,7 +148912,7 @@ function rulesFor(a) {
   }
   if (a.kind === "auth-requirement") {
     if (!/\bon-violation\s*\{/.test(src)) {
-      out.push("missing `on-violation { status ... error-code ... body ErrorEnvelope:... }`.");
+      out.push("missing `on-violation { status ... error-code ... }` (add `body ErrorEnvelope:error.envelope.standard` only when that envelope is defined in the corpus).");
     }
     if (/\brequired-role\b/.test(src)) {
       const hasBroadGlob = /selector\s+path-glob\s+"\/api\/(\*\*|\*)"/.test(src);
@@ -150497,11 +150535,27 @@ async function runContractsGenerate(options = {}) {
       if (f2.run?.error) console.log(`    \u2192 ${f2.run.error}`);
     }
   }
-  if (result.validationIssues.length > 0) {
-    O2.error(`Validation gate failed (${result.validationIssues.length} issue${result.validationIssues.length === 1 ? "" : "s"}):`);
-    for (const issue of result.validationIssues) {
-      console.log(`  ${issue.artifactKey}: ${issue.message}`);
+  const hardIssues = result.validationIssues.filter((i) => i.severity === "hard");
+  const softIssues = result.validationIssues.filter((i) => i.severity === "soft");
+  if (softIssues.length > 0) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const issue of softIssues) {
+      const line = `${issue.artifactKey}: ${issue.message}`;
+      counts.set(line, (counts.get(line) ?? 0) + 1);
     }
+    O2.warn(
+      `${counts.size} unresolved cross-reference${counts.size === 1 ? "" : "s"} (non-blocking \u2014 the referenced artifact wasn't generated; \`truecourse verify\` will flag any real drift):`
+    );
+    for (const [line, n] of counts) console.log(`  ${line}${n > 1 ? `  (\xD7${n})` : ""}`);
+  }
+  if (hardIssues.length > 0) {
+    O2.error(
+      `${hardIssues.length} artifact${hardIssues.length === 1 ? " was" : "s were"} dropped (invalid \`.tc\` \u2014 parse error or duplicate identity):`
+    );
+    for (const issue of hardIssues) console.log(`  ${issue.artifactKey}: ${issue.message}`);
+  }
+  const produced = options.diff ? result.write.proposed.length : result.write.written.length;
+  if (produced === 0 && result.validationIssues.length > 0) {
     gt("No contracts were written. Edit the spec or re-run after fixing.");
     process.exit(1);
   }
@@ -154293,7 +154347,7 @@ async function runHooksRun() {
 
 // tools/cli/src/index.ts
 var program2 = new Command();
-program2.name("truecourse").version("0.6.0-next.12").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
+program2.name("truecourse").version("0.6.0").description("TrueCourse CLI \u2014 analyze your repository and open the dashboard");
 var dashboardCmd = program2.command("dashboard").description("Start the TrueCourse dashboard and open it in your browser").option("--reconfigure", "Re-prompt for console vs background service mode").option("--service", "Run as a background service (skips mode prompt)").option("--console", "Run in this terminal (skips mode prompt)").action(async (options) => {
   if (options.service && options.console) {
     console.error("error: --service and --console are mutually exclusive");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "truecourse",
-  "version": "0.6.0-next.12",
+  "version": "0.6.0-next.13",
   "description": "Visualize your codebase architecture as an interactive graph",
   "type": "module",
   "bin": {

package/server.mjs

@@ -158105,7 +158105,7 @@ function readToolVersion() {
   if (cachedVersion)
     return cachedVersion;
   if (true) {
-    cachedVersion = "0.6.0-next.12";
+    cachedVersion = "0.6.0";
     return cachedVersion;
   }
   try {
@@ -164240,14 +164240,20 @@ Use sensible defaults when the spec doesn't spell them out:
     on-violation {
       status 401
       error-code unauthenticated
-      body ErrorEnvelope:error.envelope.standard
     }
   }
 
-Default \`on-violation\` is **always** status 401, error-code \`unauthenticated\`,
-body \`ErrorEnvelope:error.envelope.standard\` when the spec doesn't specify
-otherwise. Default selector is \`path-glob "/api/**"\` when the spec says "all
-/api/* endpoints" without naming a more specific pattern.
+Default \`on-violation\` is status 401, error-code \`unauthenticated\`. Add a
+\`body ErrorEnvelope:error.envelope.standard\` line ONLY when the spec/corpus
+actually establishes a standard error envelope \u2014 a dedicated errors /
+error-response section, an error-code catalog, or another slice that describes
+the error body shape. When the spec is SILENT about the error response body
+(common for terse auth docs that only state the scheme), OMIT the \`body\` line:
+a \`body\` reference to an envelope nothing defines is a dangling cross-reference
+that fails the validation gate, while an omitted body is faithful. See
+"Error-envelope references must be grounded" below. Default selector is
+\`path-glob "/api/**"\` when the spec says "all /api/* endpoints" without naming a
+more specific pattern.
 
 When a spec describes role-based auth ("admin only", "moderators can \u2026"), produce
 a SEPARATE \`auth-requirement\` with \`required-role <role>\`, identity
@@ -164282,7 +164288,8 @@ is the correct fallback when the slice lacks operation context.
     on-violation {
       status 403
       error-code forbidden
-      body ErrorEnvelope:error.envelope.standard
+      // body ErrorEnvelope:error.envelope.standard only when that envelope is
+      // defined in the corpus \u2014 see "Error-envelope references must be grounded".
     }
   }
 
@@ -164829,6 +164836,37 @@ response as a literal:
 - Only declare a literal \`response 401/403 on \u2026\` when the spec describes the
   response as standalone, NOT delegated to a rule.
 
+# Error-envelope references must be grounded
+
+\`ErrorEnvelope:error.envelope.standard\` is a CROSS-REFERENCE, not a literal \u2014 it
+only resolves if a matching \`error-envelope error.envelope.standard { \u2026 }\`
+artifact exists somewhere in the corpus. Emitting the reference with nothing
+defining it produces a dangling cross-reference that fails the validation gate,
+exactly like referencing an undefined \`Enum:\`. This is the same prime-directive
+rule as enums ("never reference an enum without defining it"), applied to error
+bodies.
+
+The rule applies EVERYWHERE an envelope can appear:
+\`on-violation { \u2026 body ErrorEnvelope:\u2026 }\` on auth-requirements and
+authorization-rules, and \`response \u2026 { body envelope ErrorEnvelope:\u2026 { \u2026 } }\`
+on operations.
+
+- Reference \`ErrorEnvelope:error.envelope.standard\` ONLY when the spec actually
+  establishes a standard error envelope: a dedicated errors / error-response
+  section, an error-code catalog, or prose that names "the standard error
+  envelope". In a multi-doc corpus the defining section may live in ANOTHER
+  slice \u2014 that's fine, just like an \`Enum:\` defined in a sibling slice.
+- When you reference it AND the slice in front of you is the one that describes
+  the envelope, ALSO emit the \`error-envelope error.envelope.standard { \u2026 }\`
+  artifact \u2014 mirroring the described shape; never invent fields the spec does
+  not list.
+- When the spec is SILENT about the error response body \u2014 no error section, no
+  envelope, no error codes \u2014 do NOT emit the reference at all. Omit the \`body\`
+  line from \`on-violation\`; on an operation response use a plain \`body \u2026\` only
+  if the spec gives a shape, otherwise omit it. Faithful under-specification
+  beats a dangling reference: never conjure a standard envelope just to fill the
+  slot.
+
 # Naming conventions for artifact identities
 
 Use these canonical identity formats:
@@ -165581,7 +165619,7 @@ function rulesFor(a) {
   }
   if (a.kind === "auth-requirement") {
     if (!/\bon-violation\s*\{/.test(src)) {
-      out.push("missing `on-violation { status ... error-code ... body ErrorEnvelope:... }`.");
+      out.push("missing `on-violation { status ... error-code ... }` (add `body ErrorEnvelope:error.envelope.standard` only when that envelope is defined in the corpus).");
     }
     if (/\brequired-role\b/.test(src)) {
       const hasBroadGlob = /selector\s+path-glob\s+"\/api\/(\*\*|\*)"/.test(src);