@suss/intent-ir 0.31.2 → 0.33.0

package/dist/index.js

@@ -14,6 +14,12 @@ var IntentFindingKindSchema = 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);
@@ -83,7 +89,9 @@ import {
   StorageSemanticsSchema,
   UnitInvocationSemanticsSchema
 } from "@suss/ir-core";
-var IntentSourceSchema = z2.enum(["author", "inferred", "inferred, curated"]).default("author");
+var IntentSourceSchema = z2.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) {
@@ -99,6 +107,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 = z2.enum([
   "string",
   "integer",
@@ -125,40 +151,91 @@ var BodyShapeSchema = z2.union([
     required: z2.array(z2.string()).optional()
   })
 ]);
-var RestBoundarySchema = z2.object({
+var REQUIRED = {
+  required: z2.boolean().default(false).describe("Whether the boundary needs this field.")
+};
+var InputFieldSchema = z2.union([
+  z2.strictObject({ ...REQUIRED, type: PrimitiveTypeName }),
+  z2.strictObject({
+    ...REQUIRED,
+    type: z2.literal("array"),
+    items: ShapeSchema.optional()
+  }),
+  z2.strictObject({
+    ...REQUIRED,
+    type: z2.literal("object"),
+    properties: z2.record(z2.string(), ShapeSchema).optional()
+  }),
+  z2.strictObject(REQUIRED)
+]);
+var ReceivesSchema = z2.record(z2.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 = z2.strictObject({
+  headers: z2.record(z2.string().min(1), InputFieldSchema).describe("The request headers the boundary depends on, by name.").optional(),
+  query: z2.record(z2.string().min(1), InputFieldSchema).describe("The query-string parameters the boundary depends on, by name.").optional(),
+  params: z2.record(z2.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 = z2.strictObject({
   transport: z2.literal("http").default("http"),
   semantics: z2.literal("rest"),
-  method: z2.string().min(1),
-  path: z2.string().min(1)
+  method: z2.string().min(1).describe("The HTTP method the route handles."),
+  path: z2.string().min(1).describe("The route path, written the way the framework declares it."),
+  receives: RestReceivesSchema
 });
-var FunctionCallBoundarySchema = z2.object({
+var FunctionCallBoundarySchema = z2.strictObject({
   transport: z2.string().default("in-process"),
   semantics: z2.literal("function-call"),
-  /** Repo-relative module path, when the boundary is an intra-repo unit. */
-  module: z2.string().optional(),
-  /** Named export within the module / package. */
-  exportName: z2.string().optional(),
-  /** Package name when the boundary is a public package export. */
-  package: z2.string().optional(),
-  /** Path to the export within the package (sub-path + nested names). */
-  exportPath: z2.array(z2.string()).optional()
+  module: z2.string().describe(
+    "The repo-relative module path, when the boundary is a unit inside this repository."
+  ).optional(),
+  exportName: z2.string().describe("The name the module or package exports the function under.").optional(),
+  package: z2.string().describe(
+    "The package name, when the boundary is something a package publishes."
+  ).optional(),
+  exportPath: z2.array(z2.string()).describe(
+    "The path to the export inside the package: the sub-path, then any nested names."
+  ).optional(),
+  receives: ReceivesSchema
 });
-var MessageBusBoundarySchema = z2.object({
+var MessageBusBoundarySchema = z2.strictObject({
   semantics: z2.literal("message-bus"),
-  messageBus: MessageBusSemanticsSchema.shape.messageBus,
-  channel: MessageBusSemanticsSchema.shape.channel.default(null)
+  messageBus: MessageBusSemanticsSchema.shape.messageBus.describe(
+    "Which bus carries the message, in the name suss gives that bus."
+  ),
+  channel: 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 = z2.object({
+var StorageBoundarySchema = z2.strictObject({
   semantics: z2.literal("storage"),
-  storageSystem: StorageSemanticsSchema.shape.storageSystem,
-  scope: StorageSemanticsSchema.shape.scope.default("default"),
-  container: StorageSemanticsSchema.shape.container.default(null),
-  accessPath: StorageSemanticsSchema.shape.accessPath.default(null)
+  storageSystem: 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: StorageSemanticsSchema.shape.scope.default("default").describe(
+    "The ORM, schema or deployment scope the container is in. A setup with one database uses default."
+  ),
+  container: StorageSemanticsSchema.shape.container.default(null).describe(
+    "The table, bucket, collection or index. Null when the document does not name one."
+  ),
+  accessPath: 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 = z2.object({
+var UnitInvocationBoundarySchema = z2.strictObject({
   semantics: z2.literal("unit-invocation"),
-  deploymentTarget: UnitInvocationSemanticsSchema.shape.deploymentTarget,
-  instanceName: UnitInvocationSemanticsSchema.shape.instanceName.default(null)
+  deploymentTarget: 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: 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 = z2.discriminatedUnion("semantics", [
   RestBoundarySchema,
@@ -168,18 +245,19 @@ var BoundarySchema = z2.discriminatedUnion("semantics", [
   UnitInvocationBoundarySchema
 ]);
 var ResponseOutcomeSchema = z2.object({
-  status: z2.number().int().min(100).max(599),
-  body: BodyShapeSchema.optional()
+  status: z2.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 = z2.object({
-  body: BodyShapeSchema.optional()
+  body: BodyShapeSchema.describe("The shape of the returned value.").optional()
 });
 var ThrowsOutcomeSchema = z2.object({
-  errorType: z2.string().optional()
+  errorType: z2.string().describe("The name of the error class this outcome raises.").optional()
 });
 function emptyIfNull(schema) {
-  return z2.preprocess((v) => v === null ? {} : v, schema);
+  return z2.preprocess((v) => v === null ? {} : v, schema).meta({ [ACCEPTS_NULL]: true });
 }
+var ACCEPTS_NULL = "x-suss-accepts-null";
 var ONE_OR_MORE = z2.union([
   z2.string().min(1),
   z2.array(z2.string().min(1)).min(1)
@@ -229,13 +307,19 @@ var WhenSchema = z2.union([
   z2.string().min(1),
   z2.array(z2.union([z2.string().min(1), ...WHEN_CLAUSE_BY_SUBJECT])).min(1)
 ]);
-var BoundaryTransitionSchema = z2.object({
-  id: z2.string().min(1),
-  when: WhenSchema,
-  response: emptyIfNull(ResponseOutcomeSchema).optional(),
-  returns: emptyIfNull(ReturnsOutcomeSchema).optional(),
-  throws: emptyIfNull(ThrowsOutcomeSchema).optional(),
-  results: z2.array(EffectOutcomeSchema).min(1).optional()
+var BoundaryTransitionSchema = z2.strictObject({
+  id: z2.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: z2.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, {
@@ -244,22 +328,23 @@ var BoundaryTransitionSchema = z2.object({
 function endingsOf(t) {
   return [t.response, t.returns, t.throws].filter((o) => o !== void 0);
 }
-var BoundaryIntentSchema = z2.object({
-  kind: z2.literal("boundary"),
-  /** Name PRDs reference outcomes through: `<name>.<transition-id>`. */
-  name: z2.string().min(1),
-  purpose: z2.string().min(1),
-  audience: z2.string().min(1),
+var BoundaryIntentSchema = z2.strictObject({
+  kind: z2.literal("boundary").describe("Makes this document boundary intent for one boundary."),
+  name: z2.string().min(1).describe(
+    "What this document is called. A PRD scenario links to an outcome of it as <name>.<outcome-id>."
+  ),
+  purpose: z2.string().min(1).describe("What the boundary is for, in the author's own words."),
+  audience: z2.string().min(1).describe("Who calls this boundary and depends on what it does."),
   source: IntentSourceSchema,
-  boundary: BoundarySchema,
-  transitions: z2.array(BoundaryTransitionSchema).min(1)
+  boundary: BoundarySchema.describe(
+    "Which boundary in the code the document is about."
+  ),
+  transitions: z2.array(BoundaryTransitionSchema).min(1).describe("Every outcome the boundary can produce, one entry each.")
 });
-var PrdScenarioSchema = z2.object({
-  title: z2.string().min(1).optional(),
-  /** The condition, in the author's terms. */
-  when: z2.string().min(1),
-  /** The expected outcome, in the author's terms. Always present. */
-  expect: z2.string().min(1),
+var PrdScenarioSchema = z2.strictObject({
+  title: z2.string().min(1).describe("A short name for the scenario.").optional(),
+  when: z2.string().min(1).describe("The condition the scenario covers, in the author's own words."),
+  expect: z2.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
@@ -271,15 +356,17 @@ var PrdScenarioSchema = z2.object({
    * `link`, not `then`, because a data object with a `then` property is
    * treated as a thenable by Promise resolution, a latent footgun.)
    */
-  link: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]).optional()
+  link: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]).describe(
+    "The boundary-intent outcomes this scenario is about, each written <intent-name>.<outcome-id>."
+  ).optional()
 });
-var PrdSchema = z2.object({
-  kind: z2.literal("prd"),
-  title: z2.string().min(1),
-  purpose: z2.string().min(1),
-  audience: z2.string().min(1),
+var PrdSchema = z2.strictObject({
+  kind: z2.literal("prd").describe("Makes this document a PRD, a set of scenarios for a feature."),
+  title: z2.string().min(1).describe("What this document is called."),
+  purpose: z2.string().min(1).describe("What the feature is for, in the author's own words."),
+  audience: z2.string().min(1).describe("Who the feature is for."),
   source: IntentSourceSchema,
-  scenarios: z2.array(PrdScenarioSchema).min(1)
+  scenarios: z2.array(PrdScenarioSchema).min(1).describe("The situations the feature covers, one entry each.")
 });
 var IntentDocSchema = z2.discriminatedUnion("kind", [
   BoundaryIntentSchema,
@@ -309,6 +396,7 @@ function boundaryIntentToSummary(doc) {
     audience: doc.audience,
     source: doc.source,
     boundary: toBoundaryBinding(doc.boundary),
+    receives: toReceives(doc.boundary),
     outcomes: doc.transitions.map(toOutcome)
   };
 }
@@ -364,6 +452,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 = EffectRelationSchema2.options;
 function toEffect(declared) {
   const [does, names] = Object.entries(declared).find(
@@ -492,6 +641,7 @@ var PRIMITIVE_TYPE_SHAPES = {
   unknown: { type: "unknown" }
 };
 export {
+  ACCEPTS_NULL,
   BodyShapeSchema,
   BoundarySchema,
   IntentDocSchema,
@@ -502,6 +652,8 @@ export {
   IntentRefSchema,
   IntentSourceSchema,
   blanksLeftEmpty,
+  fillBlanks,
   intentDocToSummary,
-  toBoundaryBinding
+  toBoundaryBinding,
+  toReceives
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/intent-ir",
-  "version": "0.31.2",
+  "version": "0.33.0",
   "type": "module",
   "description": "The types for the intent your team writes down, product outcomes and system behavior, in a shape suss can check the code against.",
   "keywords": [
@@ -30,15 +30,19 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./schema/intent-doc.schema.json": "./schema/intent-doc.schema.json",
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "schema",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && node scripts/generate-schema.mjs && npx biome format --write schema/intent-doc.schema.json",
+    "schema:generate": "node scripts/generate-schema.mjs && npx biome format --write schema/intent-doc.schema.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "lint": "biome check .",
@@ -49,12 +53,14 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@suss/ir-core": "0.31.2"
+    "@suss/ir-core": "0.33.0"
   },
   "devDependencies": {
+    "ajv": "^8.20.0",
     "tsup": "*",
     "typescript": "*",
     "vitest": "*",
+    "yaml": "^2.4.0",
     "zod": "^4.3.6"
   },
   "publishConfig": {