fix(design): clarify diagnostics and verify scanner Studio handoff

Author: Bill Leoutsakos

scripts/check-design-conformance-command.test.ts

@@ -1081,6 +1081,16 @@ test('large finding messages stay bounded in logs while JSON keeps full evidence
   expect(JSON.stringify(report)).toContain('a'.repeat(3000))
 })
 
+test('long authored input cannot hide warning source or permitted action', () => {
+  const report = findingReport()
+  report.findings[0].provenance!.input = 'a'.repeat(3000)
+  const annotation = githubAnnotations(report)[0]
+  expect(annotation).toContain(`source: ${TOKEN_FILE}`)
+  expect(annotation).toContain('permitted: central variable')
+  expect(annotation).toContain('input:')
+  expect(JSON.stringify(report)).toContain('a'.repeat(3000))
+})
+
 test('large unchecked summaries keep complete JSON evidence and bound human output', () => {
   const report = new ConformanceLinter().report(null)
   report.unchecked = Array.from({ length: 101 }, (_, index) => ({
@@ -1102,6 +1112,23 @@ test('large unchecked summaries keep complete JSON evidence and bound human outp
   expect(JSON.stringify(report)).toContain('component-100.tsx')
 })
 
+test('local text output names a command that exposes omitted diagnostics', () => {
+  const report = new ConformanceLinter().report(null)
+  report.unchecked = Array.from({ length: 21 }, (_, index) => ({
+    file: `component-${index}.tsx`,
+    line: 1,
+    side: 'after',
+    context: '',
+    reason: `Unresolved input ${index}`,
+    relevant: true,
+  }))
+  const output = textReport(report)
+  expect(output).toContain('bun run check:design')
+  expect(output).toContain('--output')
+  expect(output).toContain('--format json')
+  expect(output).not.toContain('component-20.tsx:1')
+})
+
 test('inspection severity is explicit and does not depend on diagnostic wording', () => {
   expect(inspectionFailure({ reason: 'Arbitrary prose', inspection: 'failed' })).toBe(true)
   expect(inspectionFailure({ reason: 'Parser failure in a supported but unresolved flow' })).toBe(

scripts/design-conformance/reporting.ts

@@ -2,8 +2,8 @@ import type { Finding, Report } from '#design-conformance/model'
 
 /** Keep source-authored newlines from becoming terminal workflow commands. */
 const line = (value: string) => value.replaceAll('\r', '\\r').replaceAll('\n', '\\n')
-const bounded = (value: string) =>
-  value.length > 1000 ? `${value.slice(0, 1000)}… [truncated; see JSON]` : value
+const bounded = (value: string, limit = 1000) =>
+  value.length > limit ? `${value.slice(0, limit)}… [truncated; see JSON]` : value
 
 export function findingCounts(report: Report) {
   return {
@@ -13,16 +13,21 @@ export function findingCounts(report: Report) {
 }
 
 function description(finding: Finding): string {
-  const parts = [finding.reason, `input: ${finding.provenance?.input ?? finding.value}`]
-  if (finding.kind === 'system-change')
+  const parts = [bounded(finding.reason, 250)]
+  if (finding.contract) parts.push(`contract: ${bounded(finding.contract, 160)}`)
+  if (finding.provenance) {
     parts.push(
-      `${finding.property}: ${JSON.stringify(finding.before ?? null)} → ${JSON.stringify(finding.value)}`
+      `source: ${bounded(finding.provenance.source, 180)}`,
+      `permitted: ${bounded(finding.provenance.permitted, 180)}`
     )
-  if (finding.contract) parts.push(`contract: ${finding.contract}`)
-  if (finding.provenance) {
-    parts.push(`source: ${finding.provenance.source}`, `permitted: ${finding.provenance.permitted}`)
-    if (finding.provenance.composition) parts.push(`through: ${finding.provenance.composition}`)
+    if (finding.provenance.composition)
+      parts.push(`through: ${bounded(finding.provenance.composition, 120)}`)
   }
+  parts.push(`input: ${bounded(finding.provenance?.input ?? finding.value, 180)}`)
+  if (finding.kind === 'system-change')
+    parts.push(
+      `${finding.property}: ${bounded(JSON.stringify(finding.before ?? null), 180)} → ${bounded(JSON.stringify(finding.value), 180)}`
+    )
   return parts.join('; ')
 }
 
@@ -68,7 +73,7 @@ export function textReport(report: Report): string {
       lines.push(`  ${bounded(description)}`)
     }
     lines.push(
-      `Showing ${Math.min(relevant.length, 20)} of ${report.unchecked.length} unchecked diagnostics; complete evidence is in the JSON report. No findings does not prove complete coverage.`
+      `Showing ${Math.min(relevant.length, 20)} of ${report.unchecked.length} unchecked diagnostics. Rerun the same bun run check:design command with --format json to print the complete report, or --output /tmp/design-check.json to save it. No findings does not prove complete coverage.`
     )
   }
   return `${lines.join('\n')}\n`

scripts/design-studio/refresh.test.mjs

@@ -154,6 +154,59 @@ function guardedRefresh() {
   return { repo, refresh }
 }
 
+test('Studio consumes the unmodified report written by the scanner CLI', () => {
+  const { repo } = guardedRefresh()
+  write(
+    repo,
+    'apps/sim/app/product/page.tsx',
+    "import { Example } from '@sim/emcn'\nexport default function Page() { return <div style={{ color: '#123456' }}><Example /></div> }\n"
+  )
+  const root = path.dirname(repo)
+  const scan = path.join(root, 'real-scan')
+  const scanner = path.resolve('scripts/design-scan/scan.ts')
+  const scanned = spawnSync(
+    process.env.DESIGN_TEST_BUN ?? 'bun',
+    ['--no-env-file', scanner, '--repo', repo, '--working-tree', '--output', scan],
+    { encoding: 'utf8', timeout: 120000 }
+  )
+  assert.ok([0, 1].includes(scanned.status), scanned.stderr)
+  const reportFile = path.join(scan, 'scan.json')
+  const reportBytes = readFileSync(reportFile)
+  const report = JSON.parse(reportBytes.toString())
+  assert.equal(report.version, 2)
+  assert.ok(report.inventory.metadata.exports.Example)
+  assert.ok(report.inventory.findings.some((finding) => finding.value === '#123456'))
+
+  const output = path.join(root, 'real-studio')
+  const refreshed = spawnSync('node', [script], {
+    env: {
+      ...process.env,
+      SIM_STUDIO_REPO: repo,
+      SIM_STUDIO_SCAN_DIR: scan,
+      SIM_STUDIO_OUTPUT: output,
+    },
+    encoding: 'utf8',
+    timeout: 120000,
+  })
+  assert.ok([0, 1].includes(refreshed.status), refreshed.stderr)
+  assert.deepEqual(readFileSync(reportFile), reportBytes)
+  const pointer = JSON.parse(readFileSync(path.join(output, 'latest.json'), 'utf8'))
+  const manifest = JSON.parse(readFileSync(path.join(pointer.path, 'manifest.json'), 'utf8'))
+  const example = components(manifest).find((entry) => entry.name === 'Example')
+  assert.ok(example)
+  assert.ok(example.variants.some((entry) => entry.id === 'component:Example:variant=filled'))
+  assert.ok(
+    example.usages.some(
+      (usage) => usage.file === 'apps/sim/app/product/page.tsx' && usage.relationship === 'direct'
+    )
+  )
+  assert.ok(
+    extras(manifest).some((entry) =>
+      report.inventory.findings.some((finding) => entry.id === `finding:${finding.id}`)
+    )
+  )
+}, 120000)
+
 test('refresh tracks source changes in imported stylesheets', () => {
   const { repo, refresh } = guardedRefresh()
   const first = refresh()