@suss/intent-ir 0.32.0 → 0.33.0

package/README.md

@@ -19,11 +19,13 @@ It is a peer of `@suss/behavioral-ir`; both build on `@suss/ir-core`. Readers (e
 
 v0: REST, function-call, message-bus, storage and unit-invocation system intent, effects as outcomes, PRD outcome intent with optional links. GraphQL, runtime-config and metric boundaries have no block yet.
 
+The file format is also published as a [JSON Schema](schema/intent-doc.schema.json), generated from the zod schemas at build time, so an editor can check a document and a tool in another language can read one without depending on this package. [Intent format](../../docs/reference/intent-format.md) goes through both document kinds field by field.
+
 ## More
 
 - [What an intent document states](./DESIGN.md)
-- [Documentation](https://nimbuscloud-ai.github.io/suss/)
-- [Every package and pack suss ships](https://nimbuscloud-ai.github.io/suss/reference/packages)
+- [Documentation](https://suss.sh/)
+- [Every package and pack suss ships](https://suss.sh/packs/catalog)
 - [Source and issues](https://github.com/nimbuscloud-ai/suss)
 
 ## Coverage

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ACCEPTS_NULL: () => ACCEPTS_NULL,
   BodyShapeSchema: () => BodyShapeSchema,
   BoundarySchema: () => BoundarySchema,
   IntentDocSchema: () => IntentDocSchema,
@@ -30,8 +31,10 @@ __export(index_exports, {
   IntentRefSchema: () => IntentRefSchema,
   IntentSourceSchema: () => IntentSourceSchema,
   blanksLeftEmpty: () => blanksLeftEmpty,
+  fillBlanks: () => fillBlanks,
   intentDocToSummary: () => intentDocToSummary,
-  toBoundaryBinding: () => toBoundaryBinding
+  toBoundaryBinding: () => toBoundaryBinding,
+  toReceives: () => toReceives
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -51,6 +54,12 @@ var IntentFindingKindSchema = import_zod.z.enum([
   // intent boundary can't be keyed, so it can't be checked
   "renamedBoundary",
   // a declared store vanished and an undeclared one of the same system appeared with the same outcomes
+  // What the boundary is handed: the `receives` block against the paths
+  // the unit reads off its input.
+  "unreadInputField",
+  // intent declares a field no transition of the unit reads
+  "undeclaredInputRead",
+  // the unit reads a path the receives block does not list
   // Outcome intent (kind: prd), scenario link coverage against system
   // intent. These concretise the proposal's "scenario not linked /
   // dangling / ambiguous" set (design/proposals/intent-specs.md);
@@ -115,7 +124,9 @@ var IntentFindingSchema = import_zod.z.object({
 // src/schema.ts
 var import_zod2 = require("zod");
 var import_ir_core = require("@suss/ir-core");
-var IntentSourceSchema = import_zod2.z.enum(["author", "inferred", "inferred, curated"]).default("author");
+var IntentSourceSchema = import_zod2.z.enum(["author", "inferred", "inferred, curated"]).default("author").describe(
+  "Where the document came from: somebody wrote it, suss inferred it, or suss inferred it and somebody has since curated it."
+);
 var UNCURATED_SOURCE = "inferred";
 var CURATED_FIELDS = ["title", "purpose", "audience", "when", "expect"];
 function blankIn(field) {
@@ -131,6 +142,24 @@ function blanksLeftEmpty(doc, failedFields) {
   }
   return CURATED_FIELDS.filter((blank) => blanks.includes(blank));
 }
+var PLACEHOLDER = "not written yet";
+var SCENARIO_BLANKS = /* @__PURE__ */ new Set(["when", "expect"]);
+function fillBlanks(doc, blanks) {
+  const filled = { ...doc };
+  for (const blank of blanks.filter((one) => !SCENARIO_BLANKS.has(one))) {
+    filled[blank] = PLACEHOLDER;
+  }
+  const scenarios = filled.scenarios;
+  if (!Array.isArray(scenarios)) {
+    return filled;
+  }
+  const inScenario = blanks.filter((one) => SCENARIO_BLANKS.has(one));
+  filled.scenarios = scenarios.map((scenario) => ({
+    ...scenario,
+    ...Object.fromEntries(inScenario.map((blank) => [blank, PLACEHOLDER]))
+  }));
+  return filled;
+}
 var PrimitiveTypeName = import_zod2.z.enum([
   "string",
   "integer",
@@ -157,40 +186,91 @@ var BodyShapeSchema = import_zod2.z.union([
     required: import_zod2.z.array(import_zod2.z.string()).optional()
   })
 ]);
-var RestBoundarySchema = import_zod2.z.object({
+var REQUIRED = {
+  required: import_zod2.z.boolean().default(false).describe("Whether the boundary needs this field.")
+};
+var InputFieldSchema = import_zod2.z.union([
+  import_zod2.z.strictObject({ ...REQUIRED, type: PrimitiveTypeName }),
+  import_zod2.z.strictObject({
+    ...REQUIRED,
+    type: import_zod2.z.literal("array"),
+    items: ShapeSchema.optional()
+  }),
+  import_zod2.z.strictObject({
+    ...REQUIRED,
+    type: import_zod2.z.literal("object"),
+    properties: import_zod2.z.record(import_zod2.z.string(), ShapeSchema).optional()
+  }),
+  import_zod2.z.strictObject(REQUIRED)
+]);
+var ReceivesSchema = import_zod2.z.record(import_zod2.z.string().min(1), InputFieldSchema).describe(
+  "The fields the boundary is handed, by field name. On a function-call boundary a name is a parameter, on a message bus it is a field of the message body."
+).optional();
+var RestReceivesSchema = import_zod2.z.strictObject({
+  headers: import_zod2.z.record(import_zod2.z.string().min(1), InputFieldSchema).describe("The request headers the boundary depends on, by name.").optional(),
+  query: import_zod2.z.record(import_zod2.z.string().min(1), InputFieldSchema).describe("The query-string parameters the boundary depends on, by name.").optional(),
+  params: import_zod2.z.record(import_zod2.z.string().min(1), InputFieldSchema).describe("The path parameters the boundary depends on, by name.").optional(),
+  body: BodyShapeSchema.describe(
+    "The shape of the request body the boundary depends on."
+  ).optional()
+}).describe("The parts of the request the boundary depends on.").optional();
+var RestBoundarySchema = import_zod2.z.strictObject({
   transport: import_zod2.z.literal("http").default("http"),
   semantics: import_zod2.z.literal("rest"),
-  method: import_zod2.z.string().min(1),
-  path: import_zod2.z.string().min(1)
+  method: import_zod2.z.string().min(1).describe("The HTTP method the route handles."),
+  path: import_zod2.z.string().min(1).describe("The route path, written the way the framework declares it."),
+  receives: RestReceivesSchema
 });
-var FunctionCallBoundarySchema = import_zod2.z.object({
+var FunctionCallBoundarySchema = import_zod2.z.strictObject({
   transport: import_zod2.z.string().default("in-process"),
   semantics: import_zod2.z.literal("function-call"),
-  /** Repo-relative module path, when the boundary is an intra-repo unit. */
-  module: import_zod2.z.string().optional(),
-  /** Named export within the module / package. */
-  exportName: import_zod2.z.string().optional(),
-  /** Package name when the boundary is a public package export. */
-  package: import_zod2.z.string().optional(),
-  /** Path to the export within the package (sub-path + nested names). */
-  exportPath: import_zod2.z.array(import_zod2.z.string()).optional()
+  module: import_zod2.z.string().describe(
+    "The repo-relative module path, when the boundary is a unit inside this repository."
+  ).optional(),
+  exportName: import_zod2.z.string().describe("The name the module or package exports the function under.").optional(),
+  package: import_zod2.z.string().describe(
+    "The package name, when the boundary is something a package publishes."
+  ).optional(),
+  exportPath: import_zod2.z.array(import_zod2.z.string()).describe(
+    "The path to the export inside the package: the sub-path, then any nested names."
+  ).optional(),
+  receives: ReceivesSchema
 });
-var MessageBusBoundarySchema = import_zod2.z.object({
+var MessageBusBoundarySchema = import_zod2.z.strictObject({
   semantics: import_zod2.z.literal("message-bus"),
-  messageBus: import_ir_core.MessageBusSemanticsSchema.shape.messageBus,
-  channel: import_ir_core.MessageBusSemanticsSchema.shape.channel.default(null)
+  messageBus: import_ir_core.MessageBusSemanticsSchema.shape.messageBus.describe(
+    "Which bus carries the message, in the name suss gives that bus."
+  ),
+  channel: import_ir_core.MessageBusSemanticsSchema.shape.channel.default(null).describe(
+    "The queue or topic the message travels on. Null when the document does not name one."
+  ),
+  receives: ReceivesSchema
 });
-var StorageBoundarySchema = import_zod2.z.object({
+var StorageBoundarySchema = import_zod2.z.strictObject({
   semantics: import_zod2.z.literal("storage"),
-  storageSystem: import_ir_core.StorageSemanticsSchema.shape.storageSystem,
-  scope: import_ir_core.StorageSemanticsSchema.shape.scope.default("default"),
-  container: import_ir_core.StorageSemanticsSchema.shape.container.default(null),
-  accessPath: import_ir_core.StorageSemanticsSchema.shape.accessPath.default(null)
+  storageSystem: import_ir_core.StorageSemanticsSchema.shape.storageSystem.default(null).describe(
+    "Which store this is: postgresql, aws.dynamodb, s3, and so on. Null when the document does not say which engine."
+  ),
+  scope: import_ir_core.StorageSemanticsSchema.shape.scope.default("default").describe(
+    "The ORM, schema or deployment scope the container is in. A setup with one database uses default."
+  ),
+  container: import_ir_core.StorageSemanticsSchema.shape.container.default(null).describe(
+    "The table, bucket, collection or index. Null when the document does not name one."
+  ),
+  accessPath: import_ir_core.StorageSemanticsSchema.shape.accessPath.default(null).describe(
+    "A secondary way into the container, such as a DynamoDB index or an Elasticsearch alias. Null means the container's own primary way in."
+  ),
+  receives: ReceivesSchema
 });
-var UnitInvocationBoundarySchema = import_zod2.z.object({
+var UnitInvocationBoundarySchema = import_zod2.z.strictObject({
   semantics: import_zod2.z.literal("unit-invocation"),
-  deploymentTarget: import_ir_core.UnitInvocationSemanticsSchema.shape.deploymentTarget,
-  instanceName: import_ir_core.UnitInvocationSemanticsSchema.shape.instanceName.default(null)
+  deploymentTarget: import_ir_core.UnitInvocationSemanticsSchema.shape.deploymentTarget.describe(
+    "What sort of deployed thing this is: a Lambda function, an ECS task's container, a plain container, a k8s deployment or an edge worker."
+  ),
+  instanceName: import_ir_core.UnitInvocationSemanticsSchema.shape.instanceName.default(null).describe(
+    "The name the deployment medium knows the unit by, such as a CloudFormation logical id. Null when the document does not name one."
+  ),
+  receives: ReceivesSchema
 });
 var BoundarySchema = import_zod2.z.discriminatedUnion("semantics", [
   RestBoundarySchema,
@@ -200,18 +280,19 @@ var BoundarySchema = import_zod2.z.discriminatedUnion("semantics", [
   UnitInvocationBoundarySchema
 ]);
 var ResponseOutcomeSchema = import_zod2.z.object({
-  status: import_zod2.z.number().int().min(100).max(599),
-  body: BodyShapeSchema.optional()
+  status: import_zod2.z.number().int().min(100).max(599).describe("The HTTP status code the response carries."),
+  body: BodyShapeSchema.describe("The shape of the response body.").optional()
 });
 var ReturnsOutcomeSchema = import_zod2.z.object({
-  body: BodyShapeSchema.optional()
+  body: BodyShapeSchema.describe("The shape of the returned value.").optional()
 });
 var ThrowsOutcomeSchema = import_zod2.z.object({
-  errorType: import_zod2.z.string().optional()
+  errorType: import_zod2.z.string().describe("The name of the error class this outcome raises.").optional()
 });
 function emptyIfNull(schema) {
-  return import_zod2.z.preprocess((v) => v === null ? {} : v, schema);
+  return import_zod2.z.preprocess((v) => v === null ? {} : v, schema).meta({ [ACCEPTS_NULL]: true });
 }
+var ACCEPTS_NULL = "x-suss-accepts-null";
 var ONE_OR_MORE = import_zod2.z.union([
   import_zod2.z.string().min(1),
   import_zod2.z.array(import_zod2.z.string().min(1)).min(1)
@@ -261,13 +342,19 @@ var WhenSchema = import_zod2.z.union([
   import_zod2.z.string().min(1),
   import_zod2.z.array(import_zod2.z.union([import_zod2.z.string().min(1), ...WHEN_CLAUSE_BY_SUBJECT])).min(1)
 ]);
-var BoundaryTransitionSchema = import_zod2.z.object({
-  id: import_zod2.z.string().min(1),
-  when: WhenSchema,
-  response: emptyIfNull(ResponseOutcomeSchema).optional(),
-  returns: emptyIfNull(ReturnsOutcomeSchema).optional(),
-  throws: emptyIfNull(ThrowsOutcomeSchema).optional(),
-  results: import_zod2.z.array(EffectOutcomeSchema).min(1).optional()
+var BoundaryTransitionSchema = import_zod2.z.strictObject({
+  id: import_zod2.z.string().min(1).describe(
+    "The outcome's name. A PRD scenario links to it as <intent-name>.<id>."
+  ),
+  when: WhenSchema.describe(
+    "What has to hold for this outcome, either as a list of clauses or as one sentence."
+  ),
+  response: emptyIfNull(ResponseOutcomeSchema).describe("This outcome sends an HTTP response.").optional(),
+  returns: emptyIfNull(ReturnsOutcomeSchema).describe("This outcome returns a value to its caller.").optional(),
+  throws: emptyIfNull(ThrowsOutcomeSchema).describe("This outcome raises an error.").optional(),
+  results: import_zod2.z.array(EffectOutcomeSchema).min(1).describe(
+    "The effects this outcome has, written in the same verbs suss ask uses: reads, writes, invokes."
+  ).optional()
 }).refine((t) => endingsOf(t).length <= 1, {
   message: "a transition ends one way: give it at most one of response, returns, or throws"
 }).refine((t) => endingsOf(t).length === 1 || t.results !== void 0, {
@@ -276,22 +363,23 @@ var BoundaryTransitionSchema = import_zod2.z.object({
 function endingsOf(t) {
   return [t.response, t.returns, t.throws].filter((o) => o !== void 0);
 }
-var BoundaryIntentSchema = import_zod2.z.object({
-  kind: import_zod2.z.literal("boundary"),
-  /** Name PRDs reference outcomes through: `<name>.<transition-id>`. */
-  name: import_zod2.z.string().min(1),
-  purpose: import_zod2.z.string().min(1),
-  audience: import_zod2.z.string().min(1),
+var BoundaryIntentSchema = import_zod2.z.strictObject({
+  kind: import_zod2.z.literal("boundary").describe("Makes this document boundary intent for one boundary."),
+  name: import_zod2.z.string().min(1).describe(
+    "What this document is called. A PRD scenario links to an outcome of it as <name>.<outcome-id>."
+  ),
+  purpose: import_zod2.z.string().min(1).describe("What the boundary is for, in the author's own words."),
+  audience: import_zod2.z.string().min(1).describe("Who calls this boundary and depends on what it does."),
   source: IntentSourceSchema,
-  boundary: BoundarySchema,
-  transitions: import_zod2.z.array(BoundaryTransitionSchema).min(1)
+  boundary: BoundarySchema.describe(
+    "Which boundary in the code the document is about."
+  ),
+  transitions: import_zod2.z.array(BoundaryTransitionSchema).min(1).describe("Every outcome the boundary can produce, one entry each.")
 });
-var PrdScenarioSchema = import_zod2.z.object({
-  title: import_zod2.z.string().min(1).optional(),
-  /** The condition, in the author's terms. */
-  when: import_zod2.z.string().min(1),
-  /** The expected outcome, in the author's terms. Always present. */
-  expect: import_zod2.z.string().min(1),
+var PrdScenarioSchema = import_zod2.z.strictObject({
+  title: import_zod2.z.string().min(1).describe("A short name for the scenario.").optional(),
+  when: import_zod2.z.string().min(1).describe("The condition the scenario covers, in the author's own words."),
+  expect: import_zod2.z.string().min(1).describe("What should happen then, in the author's own words."),
   /**
    * Optional structured link(s) to system-intent outcomes
    * (`<intent-name>.<outcome-id>`). A scenario without `link` is a
@@ -303,15 +391,17 @@ var PrdScenarioSchema = import_zod2.z.object({
    * `link`, not `then`, because a data object with a `then` property is
    * treated as a thenable by Promise resolution, a latent footgun.)
    */
-  link: import_zod2.z.union([import_zod2.z.string().min(1), import_zod2.z.array(import_zod2.z.string().min(1)).min(1)]).optional()
+  link: import_zod2.z.union([import_zod2.z.string().min(1), import_zod2.z.array(import_zod2.z.string().min(1)).min(1)]).describe(
+    "The boundary-intent outcomes this scenario is about, each written <intent-name>.<outcome-id>."
+  ).optional()
 });
-var PrdSchema = import_zod2.z.object({
-  kind: import_zod2.z.literal("prd"),
-  title: import_zod2.z.string().min(1),
-  purpose: import_zod2.z.string().min(1),
-  audience: import_zod2.z.string().min(1),
+var PrdSchema = import_zod2.z.strictObject({
+  kind: import_zod2.z.literal("prd").describe("Makes this document a PRD, a set of scenarios for a feature."),
+  title: import_zod2.z.string().min(1).describe("What this document is called."),
+  purpose: import_zod2.z.string().min(1).describe("What the feature is for, in the author's own words."),
+  audience: import_zod2.z.string().min(1).describe("Who the feature is for."),
   source: IntentSourceSchema,
-  scenarios: import_zod2.z.array(PrdScenarioSchema).min(1)
+  scenarios: import_zod2.z.array(PrdScenarioSchema).min(1).describe("The situations the feature covers, one entry each.")
 });
 var IntentDocSchema = import_zod2.z.discriminatedUnion("kind", [
   BoundaryIntentSchema,
@@ -334,6 +424,7 @@ function boundaryIntentToSummary(doc) {
     audience: doc.audience,
     source: doc.source,
     boundary: toBoundaryBinding(doc.boundary),
+    receives: toReceives(doc.boundary),
     outcomes: doc.transitions.map(toOutcome)
   };
 }
@@ -389,6 +480,67 @@ function toBoundaryBinding(boundary) {
   const build = BINDINGS[boundary.semantics];
   return build(boundary);
 }
+function toField(name, field) {
+  return {
+    path: name.split("."),
+    shape: fieldShape(field),
+    required: field.required
+  };
+}
+function fieldShape(field) {
+  if (!("type" in field)) {
+    return null;
+  }
+  const { required: _required, ...shape } = field;
+  return shapeToTypeShape(shape);
+}
+function dottedReceives(receives) {
+  return Object.entries(receives ?? {}).map(
+    ([name, field]) => toField(name, field)
+  );
+}
+var REST_SECTIONS = ["headers", "query", "params"];
+function restReceives(boundary) {
+  const receives = boundary.receives;
+  if (receives === void 0) {
+    return [];
+  }
+  const fields = REST_SECTIONS.flatMap(
+    (section) => Object.entries(receives[section] ?? {}).map(
+      ([name, field]) => toField(`${section}.${name}`, field)
+    )
+  );
+  return [...fields, ...bodyFields(receives.body)];
+}
+function bodyFields(body) {
+  if (body === void 0) {
+    return [];
+  }
+  const shape = bodyToTypeShape(body);
+  if (shape === null) {
+    return [];
+  }
+  if (shape.type !== "record") {
+    return [{ path: ["body"], shape, required: false }];
+  }
+  const required = new Set("required" in body ? body.required ?? [] : []);
+  return Object.entries(shape.properties).map(([name, property]) => ({
+    path: ["body", name],
+    shape: property,
+    required: required.has(name)
+  }));
+}
+var RECEIVES = {
+  rest: restReceives,
+  "function-call": (boundary) => dottedReceives(boundary.receives),
+  "message-bus": (boundary) => dottedReceives(boundary.receives),
+  storage: (boundary) => dottedReceives(boundary.receives),
+  "unit-invocation": (boundary) => dottedReceives(boundary.receives)
+};
+function toReceives(boundary) {
+  const read = RECEIVES[boundary.semantics];
+  return read(boundary);
+}
 var VERBS = import_ir_core2.EffectRelationSchema.options;
 function toEffect(declared) {
   const [does, names] = Object.entries(declared).find(
@@ -518,6 +670,7 @@ var PRIMITIVE_TYPE_SHAPES = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ACCEPTS_NULL,
   BodyShapeSchema,
   BoundarySchema,
   IntentDocSchema,
@@ -528,6 +681,8 @@ var PRIMITIVE_TYPE_SHAPES = {
   IntentRefSchema,
   IntentSourceSchema,
   blanksLeftEmpty,
+  fillBlanks,
   intentDocToSummary,
-  toBoundaryBinding
+  toBoundaryBinding,
+  toReceives
 });