@suss/contract-storybook 0.33.1 → 0.34.1

package/README.md

@@ -1,35 +1,37 @@
 # @suss/contract-storybook
 
-Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and says where the two disagree.
+Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and reports where the two disagree.
 
-Generate suss `BehavioralSummary[]` from [Storybook](https://storybook.js.org/) CSF3 story files. A story is a specification somebody wrote by hand: this component supports this prop configuration. Reading stories as contracts lets you ask whether a component accepts the args every story supplies, and whether every branch inferred from the component has a story that reaches it.
+This package builds suss `BehavioralSummary[]` from [Storybook](https://storybook.js.org/) CSF3 story files. A story is a specification somebody wrote by hand: this component supports this set of props. Reading stories as contracts lets you check whether a component accepts the args every story passes, and whether every branch inferred from the component has a story that reaches it.
 
 ## What this package reads
 
-`@suss/contract-storybook` parses `.stories.ts` and `.stories.tsx` files with ts-morph and looks at two things in each one.
+`@suss/contract-storybook` parses `.stories.ts` and `.stories.tsx` files with ts-morph, and reads two things in each one.
 
-The default export gives the component under test. The reader walks the default-export symbol's declarations for an object literal with a `component` property, which covers `export default { component: Button }`, `const meta = { component: Button }; export default meta;`, and `export default { ... } satisfies Meta<typeof Button>`. Parentheses, `as` expressions, and an identifier pointing at a local variable are followed through to the literal. A file whose default export never resolves to such an object is skipped, and the rest of the run continues.
+The default export gives the component under test. The reader walks the declarations of the default export's symbol, looking for an object literal with a `component` property. That covers `export default { component: Button }`, `const meta = { component: Button }; export default meta;` and `export default { ... } satisfies Meta<typeof Button>`. Parentheses, `as` expressions, and an identifier that points at a local variable are followed through to the literal. A file whose default export never resolves to such an object is skipped, and the rest of the run continues.
 
-Every other named export whose initializer resolves to an object literal is a story. Its `args` object literal becomes the story's arguments, with each property's value recorded as the source text you wrote. A shorthand property (`{ disabled }`) records its own name.
+The `component` identifier is followed through its import, any renames and any barrel re-exports, to the file that declares it. Each story file is read under the tsconfig nearest to it, so an import through one of its path aliases (`@ui/Chip/Chip`) resolves. The declaring file is written relative to the root an extract of that file's project measures from, with that project's workspace name, so the checker can find the extracted component by its own location. When the import leads to no file, for example because the module is generated or comes from a package that is not installed, no module is recorded, and the checker leaves the story unpaired.
+
+Every other named export whose initializer resolves to an object literal is a story. Its `args` object literal becomes the story's arguments, and each property's value is recorded as the source text you wrote. A shorthand property (`{ disabled }`) records its own name. Storybook gives every story the `args` set on the default export, so those are recorded on each story too, and a story's own arg replaces the meta's arg of the same name.
 
 ## What it produces
 
 One `component`-kind summary per named story export:
 
-- `identity.name` is `Component.Story`, with `exportPath` set to the story's export name and a function-call boundary binding: `transport: "in-process"`, `recognition: "react"`, and the component identifier as the export name.
-- One input per arg. The input's `role` is the arg name, and its shape is a `ref` whose name is the arg's source text, so a reader can see the concrete value that was written.
+- `identity.name` is `Component.Story`, with `exportPath` set to the story's export name, and a function-call boundary binding with `transport: "in-process"`, `recognition: "react"`, and the component identifier as the export name.
+- One input per arg. The input's `role` is the arg name, and its shape is a `ref` whose name is the arg's source text, so a reader can see the value that was written.
 - One default transition whose output is a render of the component. The reader does not evaluate the render, so the rendered tree is left unset.
-- `metadata.component.storybook` with the story name, the component name, the args map, and `provenance: "independent"`, which is what makes a story usable as a check against an inferred component summary rather than a restatement of it.
-- Confidence is `derived` at `medium`. Stories are written by people and are authoritative where they speak, and they do not enumerate everything a component does.
+- `metadata.component.storybook` with the story name, the component name, the component's module (`componentModule`, with `workspace`, `file` and `name`) and the specifier it is imported from (`componentImport`), the args map, `argReaders` when the story or its meta has `decorators` or a `render` function, `renderProps` with the props a render function passes the component as its own attributes or children, and `provenance: "independent"`. `renderProps` is left out when the render function renders the component through another element or spreads anything besides its args into it. A decorator or a render function receives the args before the component does, and the reader does not follow either, so the checker does not judge those args against the component. The provenance is what lets a story act as a check on an inferred component summary, since it was written separately from the component.
+- Confidence is `derived` at `medium`. People write stories, and a story is authoritative about what it covers, but stories do not list everything a component does.
 
 ## What it does not read
 
-- **`play` functions.** The event sequence that exercises an interactive story is not captured.
-- **`argTypes`.** Per-arg control types and option lists would inform stricter type checking and are not read today.
-- **`decorators` and `parameters`.** Storybook runtime plumbing rather than component behavior.
+- **`play` functions.** The sequence of events that drives an interactive story is not recorded.
+- **`argTypes`.** Control types and option lists per arg could support stricter type checking, but they are not read today.
+- **What `decorators`, `render` and `parameters` do.** Their presence is recorded, as above. A render function is read only for the attributes and children it gives the component's element, and the other bodies are not read. Decorators set in `.storybook/preview` apply to every story and are not seen at all.
 - **CSF1 and MDX stories.** CSF3 is the supported format.
-- **The component's own module.** The reader keeps the `component` identifier as written and does not follow the import to where the component is defined.
-- **Arg values as structured shapes.** An arg's value stays source text inside a `ref` shape rather than being parsed into a `TypeShape`.
+- **A `component` that is not a plain identifier**, such as `Icons.Chip`. No module is recorded for it.
+- **Arg values as structured shapes.** An arg's value stays as source text inside a `ref` shape, and is not parsed into a `TypeShape`.
 
 ## Worked example
 
@@ -53,9 +55,9 @@ suss contract --from storybook src/components -o summaries/stories.json
 suss check summaries/app.json summaries/stories.json
 ```
 
-The path may be one `.stories.ts[x]` file or a directory, which the CLI walks recursively for story files. Two summaries come out of the file above, `Button.Primary` and `Button.Disabled`, each with `variant` and `disabled` inputs.
+The path can be one `.stories.ts[x]` file or a directory, which the CLI searches recursively for story files. The file above produces two summaries, `Button.Primary` and `Button.Disabled`, each with `variant` and `disabled` inputs.
 
-Or programmatically, when you want control over the file set or the root that relative paths are computed against:
+To control the set of files, or the root that relative paths are computed from, call it from code:
 
 ```ts
 import { generateSummariesFromStories } from "@suss/contract-storybook";
@@ -68,7 +70,7 @@ const summaries = generateSummariesFromStories(
 
 ## Where it fits in suss
 
-Depends on `@suss/behavioral-ir` (for the IR types it produces) and `@suss/adapter-typescript` (for export resolution), with `ts-morph` as a peer dependency. This is the one contract reader that parses TypeScript, because CSF is TypeScript. It still reads a declared artifact rather than inferring behavior from a component's implementation.
+The package depends on `@suss/behavioral-ir` for the IR types it produces and on `@suss/adapter-typescript` for export resolution, with `ts-morph` as a peer dependency. It is the only contract reader that parses TypeScript, because CSF is TypeScript. It still reads a declared artifact, and does not infer behavior from a component's implementation.
 
 ## More
 

package/dist/index.cjs

@@ -38,38 +38,136 @@ var import_ts_morph = require("ts-morph");
 var import_adapter_typescript = require("@suss/adapter-typescript");
 var import_behavioral_ir = require("@suss/behavioral-ir");
 function generateSummariesFromStories(filePaths, options = {}) {
-  const project = new import_ts_morph.Project({
-    skipAddingFilesFromTsConfig: true,
-    compilerOptions: {
-      target: 99,
-      module: 99,
-      moduleResolution: 100,
-      skipLibCheck: true,
-      allowJs: true,
-      jsx: 4
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const componentModules = options.componentModules ?? true;
+  const byFile = /* @__PURE__ */ new Map();
+  const groups = componentModules ? filesByTsconfig(filePaths) : /* @__PURE__ */ new Map([[null, filePaths]]);
+  for (const [tsconfig, files] of groups) {
+    const project = projectFor(tsconfig);
+    const resolution = new import_adapter_typescript.ResolutionStore();
+    for (const sf of files.map((fp) => project.addSourceFileAtPath(fp))) {
+      const relPath = import_node_path.default.relative(projectRoot, sf.getFilePath());
+      const meta = extractMeta(sf, resolution, componentModules);
+      if (meta === null) {
+        continue;
+      }
+      byFile.set(
+        sf.getFilePath(),
+        extractStories(sf, resolution, meta).map(
+          (story) => buildSummary(story, meta, relPath)
+        )
+      );
     }
-  });
+  }
+  return filePaths.flatMap(
+    (fp) => byFile.get(import_node_path.default.resolve(fp).replace(/\\/g, "/")) ?? []
+  );
+}
+function filesByTsconfig(filePaths) {
+  const groups = /* @__PURE__ */ new Map();
   for (const fp of filePaths) {
-    project.addSourceFileAtPath(fp);
+    const tsconfig = (0, import_adapter_typescript.findNearestTsconfig)(import_node_path.default.dirname(fp));
+    const group = groups.get(tsconfig) ?? [];
+    group.push(fp);
+    groups.set(tsconfig, group);
   }
-  const projectRoot = options.projectRoot ?? process.cwd();
-  const summaries = [];
-  const resolution = new import_adapter_typescript.ResolutionStore();
-  for (const sf of project.getSourceFiles()) {
-    const absPath = sf.getFilePath();
-    const relPath = import_node_path.default.relative(projectRoot, absPath);
-    const meta = extractMeta(sf, resolution);
-    if (meta === null) {
+  return groups;
+}
+var COMPILER_OPTIONS = {
+  target: 99,
+  module: 99,
+  moduleResolution: 100,
+  skipLibCheck: true,
+  allowJs: true,
+  jsx: 4,
+  // Ambient types say nothing about a story, and a missing types folder
+  // makes every program build fail.
+  types: []
+};
+function projectFor(tsconfig) {
+  if (tsconfig !== null) {
+    try {
+      return new import_ts_morph.Project({
+        tsConfigFilePath: tsconfig,
+        skipAddingFilesFromTsConfig: true,
+        compilerOptions: { allowJs: true, jsx: 4, types: [] }
+      });
+    } catch {
+    }
+  }
+  return new import_ts_morph.Project({
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: COMPILER_OPTIONS
+  });
+}
+var ARG_READERS = ["decorators", "render"];
+function argReadersOf(storyOrMeta, resolution) {
+  const names = new Set(
+    (0, import_adapter_typescript.propertiesOf)(storyOrMeta, resolution).map(
+      (property) => (0, import_adapter_typescript.propertyNameOf)(property)
+    )
+  );
+  return ARG_READERS.filter((name) => names.has(name));
+}
+function renderPropsOf(storyOrMeta, componentName, resolution) {
+  const property = (0, import_adapter_typescript.propertiesOf)(storyOrMeta, resolution).find(
+    (candidate) => (0, import_adapter_typescript.propertyNameOf)(candidate) === "render"
+  );
+  const render = property === void 0 ? null : (0, import_adapter_typescript.propertyFunctionOf)(property, resolution);
+  if (render === null) {
+    return null;
+  }
+  const argNames = argNamesOf(render.getParameters()[0]);
+  const elements = [
+    ...render.getDescendantsOfKind(import_ts_morph.SyntaxKind.JsxOpeningElement),
+    ...render.getDescendantsOfKind(import_ts_morph.SyntaxKind.JsxSelfClosingElement)
+  ].filter((element) => element.getTagNameNode().getText() === componentName);
+  if (elements.length === 0) {
+    return null;
+  }
+  const passed = /* @__PURE__ */ new Set();
+  if (elements.some(hasJsxChildren)) {
+    passed.add("children");
+  }
+  for (const attribute of elements.flatMap((e) => e.getAttributes())) {
+    if (import_ts_morph.Node.isJsxAttribute(attribute)) {
+      passed.add(attribute.getNameNode().getText());
       continue;
     }
-    const stories = extractStories(sf, resolution);
-    for (const story of stories) {
-      summaries.push(buildSummary(story, meta, relPath));
+    if (!argNames.has(attribute.getExpression().getText())) {
+      return null;
+    }
+  }
+  return [...passed].sort();
+}
+function hasJsxChildren(element) {
+  const parent = element.getParent();
+  if (!import_ts_morph.Node.isJsxOpeningElement(element) || !import_ts_morph.Node.isJsxElement(parent)) {
+    return false;
+  }
+  return parent.getJsxChildren().some(
+    (child) => !(import_ts_morph.Node.isJsxText(child) && child.containsOnlyTriviaWhiteSpaces())
+  );
+}
+function argNamesOf(parameter) {
+  const names = /* @__PURE__ */ new Set();
+  const nameNode = parameter?.getNameNode();
+  if (nameNode === void 0) {
+    return names;
+  }
+  if (import_ts_morph.Node.isIdentifier(nameNode)) {
+    names.add(nameNode.getText());
+    return names;
+  }
+  const elements = import_ts_morph.Node.isObjectBindingPattern(nameNode) ? nameNode.getDescendantsOfKind(import_ts_morph.SyntaxKind.BindingElement).filter((element) => element.getParent() === nameNode) : [];
+  for (const element of elements) {
+    if (element.getDotDotDotToken() !== void 0) {
+      names.add(element.getName());
     }
   }
-  return summaries;
+  return names;
 }
-function extractMeta(sf, resolution) {
+function extractMeta(sf, resolution, componentModules) {
   for (const exported of resolution.exportsOf(sf).get("default") ?? []) {
     const meta = objectBehind(exported, resolution);
     if (meta === null) {
@@ -77,16 +175,63 @@ function extractMeta(sf, resolution) {
     }
     const component = (0, import_adapter_typescript.propertyOf)(meta, "component", resolution);
     if (component !== null) {
-      return { componentName: component.getText() };
+      return {
+        componentName: component.getText(),
+        componentModule: componentModules ? declaredModuleOf(component) : void 0,
+        componentImport: importSpecifierOf(component),
+        args: argsOf(meta, resolution),
+        argReaders: argReadersOf(meta, resolution),
+        renderProps: renderPropsOf(meta, component.getText(), resolution)
+      };
     }
   }
   return null;
 }
+function declaredModuleOf(component) {
+  if (!import_ts_morph.Node.isIdentifier(component)) {
+    return void 0;
+  }
+  const declaration = componentDeclarationOf(component);
+  if (declaration === void 0) {
+    return void 0;
+  }
+  const file = declaration.getSourceFile().getFilePath();
+  const tsconfig = (0, import_adapter_typescript.findNearestTsconfig)(import_node_path.default.dirname(file));
+  const root = (0, import_adapter_typescript.workspaceRootFor)(
+    tsconfig === null ? import_node_path.default.dirname(file) : import_node_path.default.dirname(tsconfig)
+  );
+  const workspace = (0, import_adapter_typescript.workspaceNameFor)(root);
+  return {
+    ...workspace === null ? {} : { workspace },
+    file: import_node_path.default.relative(root, file).replace(/\\/g, "/"),
+    name: declaredNameOf(declaration) ?? component.getText()
+  };
+}
+function componentDeclarationOf(component) {
+  return (0, import_adapter_typescript.declarationsBehind)((0, import_adapter_typescript.symbolBehind)(component)).find(
+    (declaration) => !isImportBinding(declaration)
+  );
+}
+function isImportBinding(node) {
+  return import_ts_morph.Node.isImportSpecifier(node) || import_ts_morph.Node.isImportClause(node) || import_ts_morph.Node.isNamespaceImport(node) || import_ts_morph.Node.isImportEqualsDeclaration(node);
+}
+function declaredNameOf(declaration) {
+  if (import_ts_morph.Node.isVariableDeclaration(declaration) || import_ts_morph.Node.isFunctionDeclaration(declaration) || import_ts_morph.Node.isClassDeclaration(declaration)) {
+    return declaration.getName();
+  }
+  return void 0;
+}
+function importSpecifierOf(component) {
+  if (!import_ts_morph.Node.isIdentifier(component)) {
+    return void 0;
+  }
+  return (0, import_adapter_typescript.specifierImportedAs)(component.getSourceFile(), component.getText()) ?? void 0;
+}
 function objectBehind(value, resolution) {
   const resolved = resolution.resolveObject(value);
   return resolved !== null && import_ts_morph.Node.isObjectLiteralExpression(resolved) ? resolved : null;
 }
-function extractStories(sf, resolution) {
+function extractStories(sf, resolution, meta) {
   const results = [];
   for (const [name, decls] of (0, import_adapter_typescript.exportedDeclarationsOf)(sf, resolution)) {
     if (name === "default") {
@@ -97,18 +242,23 @@ function extractStories(sf, resolution) {
       if (story === null) {
         continue;
       }
+      const ownReaders = argReadersOf(story, resolution);
       results.push({
         name,
-        args: storyArgs(story, resolution),
+        args: { ...meta.args, ...argsOf(story, resolution) },
+        argReaders: ARG_READERS.filter(
+          (reader) => meta.argReaders.includes(reader) || ownReaders.includes(reader)
+        ),
+        renderProps: ownReaders.includes("render") ? renderPropsOf(story, meta.componentName, resolution) : meta.renderProps,
         line: decl.getStartLineNumber()
       });
     }
   }
   return results;
 }
-function storyArgs(story, resolution) {
+function argsOf(storyOrMeta, resolution) {
   const args = {};
-  const written = (0, import_adapter_typescript.propertyOf)(story, "args", resolution);
+  const written = (0, import_adapter_typescript.propertyOf)(storyOrMeta, "args", resolution);
   const object = written === null ? null : (0, import_adapter_typescript.objectLiteralOf)(written, resolution);
   if (object === null) {
     return args;
@@ -129,11 +279,8 @@ function buildSummary(story, meta, filePath) {
     name,
     position: 0,
     role: name,
-    // Args are authored literals; record the source text in the shape's
-    // `ref.name` so consumers can see the concrete value. Promoting
-    // this to a structured literal shape is a follow-up (would need to
-    // parse each arg's source into a TypeShape; for v0 we surface the
-    // text).
+    // The arg's value goes in `ref.name` so a reader can see what the
+    // story passes. It is never parsed into a structured TypeShape.
     shape: { type: "ref", name: value }
   }));
   const transition = {
@@ -170,7 +317,11 @@ function buildSummary(story, meta, filePath) {
         storybook: {
           story: story.name,
           component: meta.componentName,
+          ...meta.componentModule === void 0 ? {} : { componentModule: meta.componentModule },
+          ...meta.componentImport === void 0 ? {} : { componentImport: meta.componentImport },
           args: story.args,
+          ...story.argReaders.length === 0 ? {} : { argReaders: story.argReaders },
+          ...story.renderProps === null ? {} : { renderProps: story.renderProps },
           provenance: "independent"
         }
       }

package/dist/index.d.cts

@@ -1,15 +1,35 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
+/**
+ * Reads Storybook CSF3 story files into one component summary per story.
+ * A story is a hand-written claim that its component supports one set of
+ * props. Comparing stories with the component's inferred summary shows
+ * whether the component accepts every story's args, and whether each
+ * inferred branch has a story that reaches it.
+ *
+ * Confidence is `medium`, because a story is accurate about what it covers
+ * but stories never list everything a component does. The README lists
+ * what the reader leaves out.
+ */
+
 interface StorybookStubOptions {
     /**
-     * Project root: used to compute portable relative paths in each
-     * summary's `location.file`. Defaults to the cwd.
+     * Each summary's `location.file` is relative to this, so it is the same
+     * on every machine. Defaults to the working directory.
      */
     projectRoot?: string;
+    /**
+     * False leaves out `componentModule`, the file each component is
+     * declared in. Finding it means reading the story under its tsconfig,
+     * whose path aliases make the type checker load most of the app, so a
+     * caller that only asks whether a file has stories passes false.
+     */
+    componentModules?: boolean;
 }
 /**
- * Read one or more `.stories.ts[x]` files and emit one
- * BehavioralSummary per named story export.
+ * Reads `.stories.ts` and `.stories.tsx` files and returns one summary per
+ * named story export. A file whose default export has no `component` is
+ * skipped.
  */
 declare function generateSummariesFromStories(filePaths: string[], options?: StorybookStubOptions): BehavioralSummary[];
 

package/dist/index.d.ts

@@ -1,15 +1,35 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
+/**
+ * Reads Storybook CSF3 story files into one component summary per story.
+ * A story is a hand-written claim that its component supports one set of
+ * props. Comparing stories with the component's inferred summary shows
+ * whether the component accepts every story's args, and whether each
+ * inferred branch has a story that reaches it.
+ *
+ * Confidence is `medium`, because a story is accurate about what it covers
+ * but stories never list everything a component does. The README lists
+ * what the reader leaves out.
+ */
+
 interface StorybookStubOptions {
     /**
-     * Project root: used to compute portable relative paths in each
-     * summary's `location.file`. Defaults to the cwd.
+     * Each summary's `location.file` is relative to this, so it is the same
+     * on every machine. Defaults to the working directory.
      */
     projectRoot?: string;
+    /**
+     * False leaves out `componentModule`, the file each component is
+     * declared in. Finding it means reading the story under its tsconfig,
+     * whose path aliases make the type checker load most of the app, so a
+     * caller that only asks whether a file has stories passes false.
+     */
+    componentModules?: boolean;
 }
 /**
- * Read one or more `.stories.ts[x]` files and emit one
- * BehavioralSummary per named story export.
+ * Reads `.stories.ts` and `.stories.tsx` files and returns one summary per
+ * named story export. A file whose default export has no `component` is
+ * skipped.
  */
 declare function generateSummariesFromStories(filePaths: string[], options?: StorybookStubOptions): BehavioralSummary[];
 

package/dist/index.js

@@ -2,52 +2,158 @@
 import path from "path";
 import {
   Node as N,
-  Project
+  Project,
+  SyntaxKind
 } from "ts-morph";
 import {
+  declarationsBehind,
   exportedDeclarationsOf,
+  findNearestTsconfig,
   objectLiteralOf,
   propertiesOf,
+  propertyFunctionOf,
   propertyNameOf,
   propertyOf,
   propertyValueOf,
   ResolutionStore,
-  stringValueOf
+  specifierImportedAs,
+  stringValueOf,
+  symbolBehind,
+  workspaceNameFor,
+  workspaceRootFor
 } from "@suss/adapter-typescript";
 import { functionCallBinding } from "@suss/behavioral-ir";
 function generateSummariesFromStories(filePaths, options = {}) {
-  const project = new Project({
-    skipAddingFilesFromTsConfig: true,
-    compilerOptions: {
-      target: 99,
-      module: 99,
-      moduleResolution: 100,
-      skipLibCheck: true,
-      allowJs: true,
-      jsx: 4
+  const projectRoot = options.projectRoot ?? process.cwd();
+  const componentModules = options.componentModules ?? true;
+  const byFile = /* @__PURE__ */ new Map();
+  const groups = componentModules ? filesByTsconfig(filePaths) : /* @__PURE__ */ new Map([[null, filePaths]]);
+  for (const [tsconfig, files] of groups) {
+    const project = projectFor(tsconfig);
+    const resolution = new ResolutionStore();
+    for (const sf of files.map((fp) => project.addSourceFileAtPath(fp))) {
+      const relPath = path.relative(projectRoot, sf.getFilePath());
+      const meta = extractMeta(sf, resolution, componentModules);
+      if (meta === null) {
+        continue;
+      }
+      byFile.set(
+        sf.getFilePath(),
+        extractStories(sf, resolution, meta).map(
+          (story) => buildSummary(story, meta, relPath)
+        )
+      );
     }
-  });
+  }
+  return filePaths.flatMap(
+    (fp) => byFile.get(path.resolve(fp).replace(/\\/g, "/")) ?? []
+  );
+}
+function filesByTsconfig(filePaths) {
+  const groups = /* @__PURE__ */ new Map();
   for (const fp of filePaths) {
-    project.addSourceFileAtPath(fp);
+    const tsconfig = findNearestTsconfig(path.dirname(fp));
+    const group = groups.get(tsconfig) ?? [];
+    group.push(fp);
+    groups.set(tsconfig, group);
   }
-  const projectRoot = options.projectRoot ?? process.cwd();
-  const summaries = [];
-  const resolution = new ResolutionStore();
-  for (const sf of project.getSourceFiles()) {
-    const absPath = sf.getFilePath();
-    const relPath = path.relative(projectRoot, absPath);
-    const meta = extractMeta(sf, resolution);
-    if (meta === null) {
+  return groups;
+}
+var COMPILER_OPTIONS = {
+  target: 99,
+  module: 99,
+  moduleResolution: 100,
+  skipLibCheck: true,
+  allowJs: true,
+  jsx: 4,
+  // Ambient types say nothing about a story, and a missing types folder
+  // makes every program build fail.
+  types: []
+};
+function projectFor(tsconfig) {
+  if (tsconfig !== null) {
+    try {
+      return new Project({
+        tsConfigFilePath: tsconfig,
+        skipAddingFilesFromTsConfig: true,
+        compilerOptions: { allowJs: true, jsx: 4, types: [] }
+      });
+    } catch {
+    }
+  }
+  return new Project({
+    skipAddingFilesFromTsConfig: true,
+    compilerOptions: COMPILER_OPTIONS
+  });
+}
+var ARG_READERS = ["decorators", "render"];
+function argReadersOf(storyOrMeta, resolution) {
+  const names = new Set(
+    propertiesOf(storyOrMeta, resolution).map(
+      (property) => propertyNameOf(property)
+    )
+  );
+  return ARG_READERS.filter((name) => names.has(name));
+}
+function renderPropsOf(storyOrMeta, componentName, resolution) {
+  const property = propertiesOf(storyOrMeta, resolution).find(
+    (candidate) => propertyNameOf(candidate) === "render"
+  );
+  const render = property === void 0 ? null : propertyFunctionOf(property, resolution);
+  if (render === null) {
+    return null;
+  }
+  const argNames = argNamesOf(render.getParameters()[0]);
+  const elements = [
+    ...render.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+    ...render.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement)
+  ].filter((element) => element.getTagNameNode().getText() === componentName);
+  if (elements.length === 0) {
+    return null;
+  }
+  const passed = /* @__PURE__ */ new Set();
+  if (elements.some(hasJsxChildren)) {
+    passed.add("children");
+  }
+  for (const attribute of elements.flatMap((e) => e.getAttributes())) {
+    if (N.isJsxAttribute(attribute)) {
+      passed.add(attribute.getNameNode().getText());
       continue;
     }
-    const stories = extractStories(sf, resolution);
-    for (const story of stories) {
-      summaries.push(buildSummary(story, meta, relPath));
+    if (!argNames.has(attribute.getExpression().getText())) {
+      return null;
+    }
+  }
+  return [...passed].sort();
+}
+function hasJsxChildren(element) {
+  const parent = element.getParent();
+  if (!N.isJsxOpeningElement(element) || !N.isJsxElement(parent)) {
+    return false;
+  }
+  return parent.getJsxChildren().some(
+    (child) => !(N.isJsxText(child) && child.containsOnlyTriviaWhiteSpaces())
+  );
+}
+function argNamesOf(parameter) {
+  const names = /* @__PURE__ */ new Set();
+  const nameNode = parameter?.getNameNode();
+  if (nameNode === void 0) {
+    return names;
+  }
+  if (N.isIdentifier(nameNode)) {
+    names.add(nameNode.getText());
+    return names;
+  }
+  const elements = N.isObjectBindingPattern(nameNode) ? nameNode.getDescendantsOfKind(SyntaxKind.BindingElement).filter((element) => element.getParent() === nameNode) : [];
+  for (const element of elements) {
+    if (element.getDotDotDotToken() !== void 0) {
+      names.add(element.getName());
     }
   }
-  return summaries;
+  return names;
 }
-function extractMeta(sf, resolution) {
+function extractMeta(sf, resolution, componentModules) {
   for (const exported of resolution.exportsOf(sf).get("default") ?? []) {
     const meta = objectBehind(exported, resolution);
     if (meta === null) {
@@ -55,16 +161,63 @@ function extractMeta(sf, resolution) {
     }
     const component = propertyOf(meta, "component", resolution);
     if (component !== null) {
-      return { componentName: component.getText() };
+      return {
+        componentName: component.getText(),
+        componentModule: componentModules ? declaredModuleOf(component) : void 0,
+        componentImport: importSpecifierOf(component),
+        args: argsOf(meta, resolution),
+        argReaders: argReadersOf(meta, resolution),
+        renderProps: renderPropsOf(meta, component.getText(), resolution)
+      };
     }
   }
   return null;
 }
+function declaredModuleOf(component) {
+  if (!N.isIdentifier(component)) {
+    return void 0;
+  }
+  const declaration = componentDeclarationOf(component);
+  if (declaration === void 0) {
+    return void 0;
+  }
+  const file = declaration.getSourceFile().getFilePath();
+  const tsconfig = findNearestTsconfig(path.dirname(file));
+  const root = workspaceRootFor(
+    tsconfig === null ? path.dirname(file) : path.dirname(tsconfig)
+  );
+  const workspace = workspaceNameFor(root);
+  return {
+    ...workspace === null ? {} : { workspace },
+    file: path.relative(root, file).replace(/\\/g, "/"),
+    name: declaredNameOf(declaration) ?? component.getText()
+  };
+}
+function componentDeclarationOf(component) {
+  return declarationsBehind(symbolBehind(component)).find(
+    (declaration) => !isImportBinding(declaration)
+  );
+}
+function isImportBinding(node) {
+  return N.isImportSpecifier(node) || N.isImportClause(node) || N.isNamespaceImport(node) || N.isImportEqualsDeclaration(node);
+}
+function declaredNameOf(declaration) {
+  if (N.isVariableDeclaration(declaration) || N.isFunctionDeclaration(declaration) || N.isClassDeclaration(declaration)) {
+    return declaration.getName();
+  }
+  return void 0;
+}
+function importSpecifierOf(component) {
+  if (!N.isIdentifier(component)) {
+    return void 0;
+  }
+  return specifierImportedAs(component.getSourceFile(), component.getText()) ?? void 0;
+}
 function objectBehind(value, resolution) {
   const resolved = resolution.resolveObject(value);
   return resolved !== null && N.isObjectLiteralExpression(resolved) ? resolved : null;
 }
-function extractStories(sf, resolution) {
+function extractStories(sf, resolution, meta) {
   const results = [];
   for (const [name, decls] of exportedDeclarationsOf(sf, resolution)) {
     if (name === "default") {
@@ -75,18 +228,23 @@ function extractStories(sf, resolution) {
       if (story === null) {
         continue;
       }
+      const ownReaders = argReadersOf(story, resolution);
       results.push({
         name,
-        args: storyArgs(story, resolution),
+        args: { ...meta.args, ...argsOf(story, resolution) },
+        argReaders: ARG_READERS.filter(
+          (reader) => meta.argReaders.includes(reader) || ownReaders.includes(reader)
+        ),
+        renderProps: ownReaders.includes("render") ? renderPropsOf(story, meta.componentName, resolution) : meta.renderProps,
         line: decl.getStartLineNumber()
       });
     }
   }
   return results;
 }
-function storyArgs(story, resolution) {
+function argsOf(storyOrMeta, resolution) {
   const args = {};
-  const written = propertyOf(story, "args", resolution);
+  const written = propertyOf(storyOrMeta, "args", resolution);
   const object = written === null ? null : objectLiteralOf(written, resolution);
   if (object === null) {
     return args;
@@ -107,11 +265,8 @@ function buildSummary(story, meta, filePath) {
     name,
     position: 0,
     role: name,
-    // Args are authored literals; record the source text in the shape's
-    // `ref.name` so consumers can see the concrete value. Promoting
-    // this to a structured literal shape is a follow-up (would need to
-    // parse each arg's source into a TypeShape; for v0 we surface the
-    // text).
+    // The arg's value goes in `ref.name` so a reader can see what the
+    // story passes. It is never parsed into a structured TypeShape.
     shape: { type: "ref", name: value }
   }));
   const transition = {
@@ -148,7 +303,11 @@ function buildSummary(story, meta, filePath) {
         storybook: {
           story: story.name,
           component: meta.componentName,
+          ...meta.componentModule === void 0 ? {} : { componentModule: meta.componentModule },
+          ...meta.componentImport === void 0 ? {} : { componentImport: meta.componentImport },
           args: story.args,
+          ...story.argReaders.length === 0 ? {} : { argReaders: story.argReaders },
+          ...story.renderProps === null ? {} : { renderProps: story.renderProps },
           provenance: "independent"
         }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-storybook",
-  "version": "0.33.1",
+  "version": "0.34.1",
   "type": "module",
   "description": "Turn Storybook CSF stories into a suss contract and check the props they pass against the React components that receive them.",
   "keywords": [
@@ -14,7 +14,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/storybook#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",
@@ -47,8 +47,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@suss/adapter-typescript": "0.33.1",
-    "@suss/behavioral-ir": "0.33.1"
+    "@suss/adapter-typescript": "0.34.1",
+    "@suss/behavioral-ir": "0.34.1"
   },
   "devDependencies": {
     "tsup": "*",