create-cs-object 0.1.1 → 0.1.3

package/template/references/README.md

@@ -3,3 +3,137 @@
 Keep source documents or links here. Record the relevant page or clause, edition,
 and the assumptions each source supports. The starter uses the elementary
 rectangle area relation and has no external engineering reference case.
+
+## Bind an independent case
+
+A CLI reference file contains `referenceVersion: "1"` and a `cases` array.
+Each case records an ID, revision, independent basis, source/input binding,
+and expected values for every calculated symbol, including intermediates.
+Each expected entry needs the captured symbol ID, independently established
+value and matching unit. A comparison of only public outputs is a separate
+numerical check; it does not provide complete CLI reference coverage.
+
+This recipe is for the unchanged rectangle starter. Establish its expected
+area independently first: a 2 m by 3 m rectangle has area 6 m². The verification
+report supplies only source hashes, function and input metadata for binding;
+the expected value below is the hand-derived 6, not a captured result.
+
+From the project root in a POSIX shell:
+
+```sh
+PYTHON="$PWD/.venv/bin/python" npx --no-install cso verify calculations/report.cso.py \
+  --function calculate --input width=2 --input height=3 --format json \
+  > references/rectangle-check.json
+```
+
+Create `references/rectangle-reference.json` with the full case shape:
+
+```sh
+./.venv/bin/python - <<'PY'
+import json
+from pathlib import Path
+
+report = json.loads(Path("references/rectangle-check.json").read_text(encoding="utf-8"))
+if not report["ok"]:
+    raise SystemExit("Resolve verification diagnostics before binding a case")
+fields = (
+    "entryModuleId", "entrySourceHash", "sourceClosureHash", "function",
+    "resolvedInputs", "resolvedInputKinds",
+)
+reference = {
+    "referenceVersion": "1",
+    "cases": [{
+        "id": "rectangle-2-by-3",
+        "revision": "1",
+        "basis": {
+            "method": "Hand-derived rectangle area",
+            "derivation": "Perpendicular sides: 2 m times 3 m equals 6 m^2.",
+            "sourceDescription": "Elementary geometry for the stated rectangle.",
+        },
+        "binding": {name: report["provenance"][name] for name in fields},
+        "expected": [{
+            "symbolId": '["symbol","root","area"]',
+            "value": 6,
+            "unit": "m^2",
+        }],
+    }],
+}
+Path("references/rectangle-reference.json").write_text(
+    json.dumps(reference, indent=2) + "\n", encoding="utf-8", newline="\n"
+)
+PY
+PYTHON="$PWD/.venv/bin/python" npx --no-install cso verify calculations/report.cso.py \
+  --function calculate --input width=2 --input height=3 \
+  --reference references/rectangle-reference.json --format json
+```
+
+In PowerShell 5.1 or 7, run the following block instead. It captures only the
+verification metadata needed to bind the independently derived value `6`.
+The JSON stays inside PowerShell until the file write, so native argument
+quoting cannot alter it. `Join-Path $PWD` gives the .NET writer an absolute path.
+
+<!-- docs:reference-authoring:start -->
+```powershell
+$env:PYTHON = Join-Path $PWD '.venv\Scripts\python.exe'
+$cso = Join-Path $PWD 'node_modules\.bin\cso.cmd'
+$source = Join-Path $PWD 'calculations\report.cso.py'
+$utf8 = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = $utf8
+$reportText = & $cso verify $source --function calculate --input width=2 --input height=3 --format json
+if ($LASTEXITCODE -ne 0) { throw 'Calculation verification failed.' }
+$report = ($reportText -join "`n") | ConvertFrom-Json
+if (-not $report.ok) { throw 'Resolve verification diagnostics before binding a case.' }
+$binding = [ordered]@{}
+foreach ($name in @('entryModuleId', 'entrySourceHash', 'sourceClosureHash', 'function', 'resolvedInputs', 'resolvedInputKinds')) {
+    $binding[$name] = $report.provenance.$name
+}
+$reference = [ordered]@{
+    referenceVersion = '1'
+    cases = @([ordered]@{
+        id = 'rectangle-2-by-3'
+        revision = '1'
+        basis = [ordered]@{
+            method = 'Hand-derived rectangle area'
+            derivation = 'Perpendicular sides: 2 m times 3 m equals 6 m^2.'
+            sourceDescription = 'Elementary geometry for the stated rectangle.'
+        }
+        binding = $binding
+        expected = @([ordered]@{
+            symbolId = '["symbol","root","area"]'
+            value = 6
+            unit = 'm^2'
+        })
+    })
+}
+$referencePath = Join-Path $PWD 'references\rectangle-reference.json'
+$json = ($reference | ConvertTo-Json -Depth 20).Replace("`r`n", "`n") + "`n"
+[System.IO.File]::WriteAllText($referencePath, $json, $utf8)
+& $cso verify $source --function calculate --input width=2 --input height=3 --reference $referencePath --format json
+if ($LASTEXITCODE -ne 0) { throw 'Independent reference verification failed.' }
+```
+<!-- docs:reference-authoring:end -->
+
+This writer produces UTF-8 without a BOM and uses LF. Do not use `>` or
+`Out-File` to save source or JSON in Windows PowerShell 5.1; their default
+encoding differs from this file format. The console encoding assignment makes
+UTF-8 CLI output safe to capture before `ConvertFrom-Json`, including Unicode
+paths and diagnostics.
+
+Check that `checks.independentReferenceAgreement.status` is `passed` with one checked
+symbol. To use the case in the browser, add
+`"reference": "references/rectangle-reference.json"` to the starter entry in
+`reports.json`, restart `npm run dev`, and calculate with width 2 and height 3.
+The same `--reference` option works with `cso html` and `cso pdf`.
+
+For a replacement calculation, establish expected values for all calculated
+symbols from a cited method or independent implementation. Use the symbol IDs
+from its execution evidence, exact documented units, and the binding for that
+source, function and input case. Check the reference against that execution.
+Different inputs need their own cases; an unmatched case is `not_applicable` in
+CLI reports and remains pending in the browser.
+
+Source edits invalidate a binding, including edits to explanation text. After
+reviewing a change, explicitly revise the binding and case revision while
+preserving independently established expected values. Update expected values
+only when their independent derivation changes, and record why. Reference
+agreement does not establish human engineering approval.

package/template/reports.json

@@ -0,0 +1,8 @@
+[
+  {
+    "id": "rectangle-area",
+    "title": "Rectangle area",
+    "source": "calculations/report.cso.py",
+    "function": "calculate"
+  }
+]

package/template/scripts/dev.ts

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawn, type ChildProcess } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
@@ -10,48 +10,119 @@ const python = join(
   '.venv',
   process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python',
 );
-try {
+
+function awaitOrigin(child: ChildProcess): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let stdout = '';
+    const finish = (error?: Error, origin?: string) => {
+      clearTimeout(timeout);
+      child.off('error', onError);
+      child.off('exit', onExit);
+      child.stdout?.off('data', onData);
+      if (error) reject(error);
+      else if (origin) resolve(origin);
+    };
+    const onError = (error: Error) => finish(error);
+    const onExit = (code: number | null) =>
+      finish(new Error(`Calculation server exited (${code})`));
+    const onData = (chunk: string) => {
+      stdout += chunk;
+      const match = /CSO dev (http:\/\/127\.0\.0\.1:\d+)/.exec(stdout);
+      if (match?.[1]) finish(undefined, match[1]);
+    };
+    const timeout = setTimeout(
+      () => finish(new Error('Calculation server did not start')),
+      30_000,
+    );
+    child.once('error', onError);
+    child.once('exit', onExit);
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', onData);
+  });
+}
+
+async function main() {
   if (!existsSync(python))
     throw new Error(
       'Run npm run setup to prepare the project Python environment.',
     );
+  const { loadReports } = await import('./reports.ts');
+  const args = process.argv.slice(2);
+  if (args.length !== 0 && (args.length !== 2 || args[0] !== '--port'))
+    throw new Error('Usage: npm run dev -- [--port 0-65535]');
+  const spelling = args[1] ?? '5173';
+  if (!/^\d+$/.test(spelling) || Number(spelling) > 65535)
+    throw new Error('--port must be an integer between 0 and 65535');
+  const port = Number(spelling);
+  const reports = loadReports(project);
   const require = createRequire(import.meta.url);
   const cli = join(
     dirname(require.resolve('@cs-object/cli/package.json')),
     'dist/cli.js',
   );
-  const child = spawn(
-    process.execPath,
-    [
-      cli,
-      'dev',
-      'calculations/report.cso.py',
-      '--function',
-      'calculate',
-      ...process.argv.slice(2),
-    ],
-    {
-      cwd: project,
-      env: { ...process.env, PYTHON: python },
-      stdio: 'inherit',
-    },
-  );
-  const interrupt = () => child.kill('SIGINT');
-  const terminate = () => child.kill('SIGTERM');
-  process.on('SIGINT', interrupt);
-  process.on('SIGTERM', terminate);
-  child.once('error', (error) => {
-    process.stderr.write(`${error.message}\n`);
-  });
-  child.once('close', (code, signal) => {
-    process.off('SIGINT', interrupt);
-    process.off('SIGTERM', terminate);
-    process.exitCode =
-      code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1);
-  });
-} catch (error) {
+  const children: ChildProcess[] = [];
+  let vite: Awaited<ReturnType<typeof import('vite').createServer>> | undefined;
+  let stopping = false;
+  const stop = () => {
+    if (stopping) return;
+    stopping = true;
+    for (const child of children) child.kill('SIGTERM');
+    if (vite) void vite.close();
+  };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+  try {
+    const backends = [];
+    for (const report of reports) {
+      const child = spawn(
+        process.execPath,
+        [
+          cli,
+          'dev',
+          report.source,
+          '--function',
+          report.function,
+          ...(report.reference ? ['--reference', report.reference] : []),
+          '--port',
+          '0',
+        ],
+        {
+          cwd: project,
+          env: { ...process.env, PYTHON: python },
+          stdio: ['ignore', 'pipe', 'inherit'],
+        },
+      );
+      children.push(child);
+      const origin = await awaitOrigin(child);
+      child.once('exit', (code) => {
+        if (stopping) return;
+        process.stderr.write(
+          `Calculation server for ${report.id} exited (${code}).\n`,
+        );
+        process.exitCode = code || 1;
+        stop();
+      });
+      backends.push({ id: report.id, title: report.title, origin });
+    }
+    process.env.CSO_REPORT_BACKENDS = JSON.stringify(backends);
+    const { createServer } = await import('vite');
+    vite = await createServer({
+      server: { host: '127.0.0.1', port, strictPort: port !== 0 },
+    });
+    await vite.listen();
+    const address = vite.httpServer?.address();
+    if (!address || typeof address === 'string')
+      throw new Error('Vite has no localhost address');
+    process.stdout.write(`CSO dev http://127.0.0.1:${address.port}\n`);
+  } catch (error) {
+    stop();
+    throw error;
+  }
+}
+
+main().catch((error: unknown) => {
   process.stderr.write(
     `${error instanceof Error ? error.message : String(error)}\n`,
   );
   process.exitCode = 1;
-}
+});

package/template/scripts/reports.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PythonIdentifierSchema } from '@cs-object/core';
+import { z } from 'zod';
+
+const ReportSchema = z.strictObject({
+  id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+  title: z.string().min(1),
+  source: z.string().regex(/^calculations\/(?!.*\.\.\/)[^/].*\.cso\.py$/),
+  function: PythonIdentifierSchema,
+  reference: z.string().optional(),
+});
+
+export type Report = z.infer<typeof ReportSchema>;
+
+export function loadReports(project: string): Report[] {
+  const reports = z
+    .array(ReportSchema)
+    .min(1)
+    .parse(JSON.parse(readFileSync(join(project, 'reports.json'), 'utf8')));
+  if (new Set(reports.map(({ id }) => id)).size !== reports.length)
+    throw new Error('reports.json contains duplicate report IDs');
+  return reports;
+}