@suss/intent-ir 0.0.1

package/dist/index.js

@@ -0,0 +1,320 @@
+// src/findings.ts
+import { z } from "zod";
+var IntentFindingKindSchema = z.enum([
+  // System intent (kind: boundary) vs code:
+  "uncoveredOutcome",
+  // intent declares an outcome the code never produces
+  "unimplementedBoundary",
+  // intent boundary has no implementing code at all
+  "outcomeShapeMismatch",
+  // a matched outcome whose body shapes disagree
+  "undeclaredOutcome",
+  // code produces a REST status the intent doesn't declare
+  "unkeyableBoundary",
+  // intent boundary can't be keyed, so it can't be checked
+  // Outcome intent (kind: prd) — scenario link coverage against system
+  // intent. These concretise the proposal's "scenario not linked /
+  // dangling / ambiguous" set (docs/internal/proposals/intent-specs.md);
+  // the proposal deferred concrete names to implementation time.
+  "unlinkedScenario",
+  // scenario carries no structured link (info — a valid pending state)
+  "danglingScenarioLink",
+  // link names an intent / outcome no boundary intent declares
+  "ambiguousScenarioLink"
+  // link resolves to two or more boundary intents sharing the name
+]);
+var IntentFindingSeveritySchema = z.enum(["error", "warning", "info"]);
+var IntentRefSchema = z.object({
+  /** The intent doc's `name` (boundary) or `title` (prd). */
+  name: z.string(),
+  /** The declared outcome id, when the finding is outcome-specific. */
+  outcomeId: z.string().optional()
+});
+var IntentFindingSuppressionSchema = z.object({
+  /** The rule's human-written justification. */
+  reason: z.string(),
+  effect: z.enum(["mark", "downgrade", "hide"]),
+  /** Original severity, present only when effect is "downgrade". */
+  originalSeverity: IntentFindingSeveritySchema.optional()
+});
+var IntentFindingSchema = z.object({
+  kind: IntentFindingKindSchema,
+  severity: IntentFindingSeveritySchema,
+  /**
+   * Human-readable boundary label — e.g. `GET /users/:id` or
+   * `fn:@suss/cli::contract`. The key the intent and code were paired on.
+   */
+  boundary: z.string(),
+  /** The intent side of the finding. */
+  intent: IntentRefSchema,
+  /**
+   * The matched code summary as `${file}::${name}`, when the finding
+   * concerns a specific implementation. Absent for unimplementedBoundary.
+   */
+  code: z.string().optional(),
+  /**
+   * PRD-scenario extension — present only on outcome-intent findings
+   * (unlinkedScenario / danglingScenarioLink / ambiguousScenarioLink).
+   * Identifies the scenario (by its optional title) and the qualified
+   * outcome ref (`<intent-name>.<outcome-id>`) that failed to resolve.
+   * The peer / boundary findings leave it unset — this is the "intent
+   * finding extension" decision 2 of the proposal anticipated.
+   */
+  scenario: z.object({
+    title: z.string().optional(),
+    link: z.string().optional()
+  }).optional(),
+  message: z.string(),
+  /** Present when a .sussignore rule matched this finding. */
+  suppressed: IntentFindingSuppressionSchema.optional()
+});
+
+// src/schema.ts
+import { z as z2 } from "zod";
+var IntentSourceSchema = z2.enum(["author", "inferred", "inferred, curated"]).default("author");
+var PrimitiveTypeName = z2.enum([
+  "string",
+  "integer",
+  "number",
+  "boolean",
+  "null",
+  "unknown"
+]);
+var ShapeSchema = z2.lazy(
+  () => z2.union([
+    z2.object({ type: PrimitiveTypeName }),
+    z2.object({ type: z2.literal("array"), items: ShapeSchema.optional() }),
+    z2.object({
+      type: z2.literal("object"),
+      properties: z2.record(z2.string(), ShapeSchema).optional(),
+      required: z2.array(z2.string()).optional()
+    })
+  ])
+);
+var BodyShapeSchema = z2.union([
+  ShapeSchema,
+  z2.object({
+    properties: z2.record(z2.string(), ShapeSchema).optional(),
+    required: z2.array(z2.string()).optional()
+  })
+]);
+var RestBoundarySchema = z2.object({
+  transport: z2.literal("http").default("http"),
+  semantics: z2.literal("rest"),
+  method: z2.string().min(1),
+  path: z2.string().min(1)
+});
+var FunctionCallBoundarySchema = z2.object({
+  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()
+});
+var BoundarySchema = z2.discriminatedUnion("semantics", [
+  RestBoundarySchema,
+  FunctionCallBoundarySchema
+]);
+var ResponseOutcomeSchema = z2.object({
+  status: z2.number().int().min(100).max(599),
+  body: BodyShapeSchema.optional()
+});
+var ReturnsOutcomeSchema = z2.object({
+  body: BodyShapeSchema.optional()
+});
+var ThrowsOutcomeSchema = z2.object({
+  errorType: z2.string().optional()
+});
+function emptyIfNull(schema) {
+  return z2.preprocess((v) => v === null ? {} : v, schema);
+}
+var BoundaryTransitionSchema = z2.object({
+  id: z2.string().min(1),
+  when: z2.string().min(1),
+  response: emptyIfNull(ResponseOutcomeSchema).optional(),
+  returns: emptyIfNull(ReturnsOutcomeSchema).optional(),
+  throws: emptyIfNull(ThrowsOutcomeSchema).optional()
+}).refine(
+  (t) => [t.response, t.returns, t.throws].filter((o) => o !== void 0).length === 1,
+  {
+    message: "each transition must declare exactly one outcome: response, returns, or throws"
+  }
+);
+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),
+  source: IntentSourceSchema,
+  boundary: BoundarySchema,
+  transitions: z2.array(BoundaryTransitionSchema).min(1)
+});
+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),
+  /**
+   * Optional structured link(s) to system-intent outcomes
+   * (`<intent-name>.<outcome-id>`). A scenario without `link` is a
+   * valid pending-link state: fully human-readable, not yet machine-
+   * linked. The link is filled in later by a facilitator (a person, a
+   * platform, or an LLM at authoring time) — never required to author.
+   *
+   * (The human-readable parts are `when` / `expect`; the field is named
+   * `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()
+});
+var PrdSchema = z2.object({
+  kind: z2.literal("prd"),
+  title: z2.string().min(1),
+  purpose: z2.string().min(1),
+  audience: z2.string().min(1),
+  source: IntentSourceSchema,
+  scenarios: z2.array(PrdScenarioSchema).min(1)
+});
+var IntentDocSchema = z2.discriminatedUnion("kind", [
+  BoundaryIntentSchema,
+  PrdSchema
+]);
+
+// src/summary.ts
+import {
+  functionCallBinding,
+  restBinding
+} from "@suss/ir-core";
+function intentDocToSummary(doc) {
+  if (doc.kind === "prd") {
+    return prdToSummary(doc);
+  }
+  return boundaryIntentToSummary(doc);
+}
+function boundaryIntentToSummary(doc) {
+  return {
+    kind: "boundary",
+    name: doc.name,
+    purpose: doc.purpose,
+    audience: doc.audience,
+    source: doc.source,
+    boundary: toBoundaryBinding(doc.boundary),
+    outcomes: doc.transitions.map(toOutcome)
+  };
+}
+function prdToSummary(doc) {
+  return {
+    kind: "prd",
+    title: doc.title,
+    purpose: doc.purpose,
+    audience: doc.audience,
+    source: doc.source,
+    scenarios: doc.scenarios.map((s) => ({
+      title: s.title ?? null,
+      when: s.when,
+      expect: s.expect,
+      link: s.link === void 0 ? [] : Array.isArray(s.link) ? s.link : [s.link]
+    }))
+  };
+}
+function toBoundaryBinding(boundary) {
+  if (boundary.semantics === "rest") {
+    return restBinding({
+      transport: boundary.transport,
+      method: boundary.method,
+      path: boundary.path,
+      recognition: "intent"
+    });
+  }
+  return functionCallBinding({
+    transport: boundary.transport,
+    recognition: "intent",
+    ...boundary.module !== void 0 ? { module: boundary.module } : {},
+    ...boundary.exportName !== void 0 ? { exportName: boundary.exportName } : {},
+    ...boundary.package !== void 0 ? { package: boundary.package } : {},
+    ...boundary.exportPath !== void 0 ? { exportPath: boundary.exportPath } : {}
+  });
+}
+function toOutcome(t) {
+  const base = { id: t.id, when: t.when };
+  if (t.response !== void 0) {
+    return {
+      ...base,
+      kind: "response",
+      status: t.response.status,
+      body: t.response.body ? bodyToTypeShape(t.response.body) : null,
+      errorType: null
+    };
+  }
+  if (t.returns !== void 0) {
+    return {
+      ...base,
+      kind: "return",
+      status: null,
+      body: t.returns.body ? bodyToTypeShape(t.returns.body) : null,
+      errorType: null
+    };
+  }
+  return {
+    ...base,
+    kind: "throw",
+    status: null,
+    body: null,
+    errorType: t.throws?.errorType ?? null
+  };
+}
+function bodyToTypeShape(body) {
+  if (!("type" in body)) {
+    if (body.properties === void 0) {
+      return null;
+    }
+    return recordShape(body.properties);
+  }
+  return shapeToTypeShape(body);
+}
+function shapeToTypeShape(shape) {
+  if (shape.type === "array") {
+    return {
+      type: "array",
+      items: shape.items !== void 0 ? shapeToTypeShape(shape.items) : { type: "unknown" }
+    };
+  }
+  if (shape.type === "object") {
+    return recordShape(shape.properties ?? {});
+  }
+  return PRIMITIVE_TYPE_SHAPES[shape.type];
+}
+function recordShape(authored) {
+  const properties = {};
+  for (const [name, prop] of Object.entries(authored)) {
+    properties[name] = shapeToTypeShape(prop);
+  }
+  return { type: "record", properties };
+}
+var PRIMITIVE_TYPE_SHAPES = {
+  string: { type: "text" },
+  integer: { type: "integer" },
+  number: { type: "number" },
+  boolean: { type: "boolean" },
+  null: { type: "null" },
+  unknown: { type: "unknown" }
+};
+export {
+  BodyShapeSchema,
+  BoundarySchema,
+  IntentDocSchema,
+  IntentFindingKindSchema,
+  IntentFindingSchema,
+  IntentFindingSeveritySchema,
+  IntentFindingSuppressionSchema,
+  IntentRefSchema,
+  IntentSourceSchema,
+  intentDocToSummary
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@suss/intent-ir",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Intent IR for suss — the team-authored side of the loop. PRD (outcome) intent and system intent, in shapes that pair against derived behavioral summaries.",
+  "keywords": [
+    "suss",
+    "intent",
+    "prd",
+    "ir"
+  ],
+  "license": "Apache-2.0",
+  "author": "Nimbus Cloud AI LLC",
+  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/intent-ir#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimbuscloud-ai/suss.git",
+    "directory": "packages/intent-ir"
+  },
+  "bugs": {
+    "url": "https://github.com/nimbuscloud-ai/suss/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "dependencies": {
+    "@suss/ir-core": "0.0.1"
+  },
+  "devDependencies": {
+    "tsup": "*",
+    "typescript": "*",
+    "vitest": "*",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}