@boxxy/closeout 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the boxxy authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+<div align="center">
+  <h1>@boxxy/closeout</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <p>
+    <a href="https://www.npmjs.com/package/@boxxy/closeout"><img src="https://img.shields.io/npm/v/@boxxy/closeout" alt="npm version"></a>
+    <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  </p>
+
+  <p>
+    <a href="../../docs/design/boxxy/README.md">Documentation</a>
+  </p>
+</div>
+
+boxxy's close-out parser. It checks the close-out an agent sends at the end of a build attempt, and
+splits the work the agent found into new items to file and matches of items already open.
+
+The package does no I/O: the caller passes in the item, the attempt's evidence rows and the open
+items.
+
+## Install
+
+Install the package from [npm](https://www.npmjs.com/package/@boxxy/closeout) with Bun:
+
+```bash
+bun add @boxxy/closeout
+```
+
+The package runs on [Bun](https://bun.sh) 1.3 or newer.
+
+## Features
+
+- `buildCloseOutParser`, which returns the parsed close-out, or every problem with it in one pass
+  ([the build close-out](../../docs/design/boxxy/slice-1.md#the-build-close-out)).
+- `missingCriteria`, which lists the item's criteria that the close-out cites no evidence for.
+- `dedupeOpenItems` and `normaliseTitle`, which match each open item the agent reports to an open
+  item with the same title.
+
+## Documentation
+
+The [close-outs design](../../docs/design/boxxy/close-outs.md) says what a close-out holds and why,
+and [`06-closeouts.ts`](../../docs/design/boxxy/sketches/06-closeouts.ts) gives the shapes.

package/dist/build-close-out-parser.d.ts

@@ -0,0 +1,2 @@
+import type { BuildCloseOut, CloseOutParser } from '@boxxy/model';
+export declare const buildCloseOutParser: CloseOutParser<BuildCloseOut>;

package/dist/dedupe-open-items.d.ts

@@ -0,0 +1,5 @@
+import type { ItemId, ItemView, OpenItem } from '@boxxy/model';
+export declare function dedupeOpenItems(entries: readonly OpenItem[], open: readonly ItemView[]): {
+    readonly file: readonly OpenItem[];
+    readonly matched: readonly ItemId[];
+};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { buildCloseOutParser } from './build-close-out-parser.ts';
+export { dedupeOpenItems } from './dedupe-open-items.ts';
+export { missingCriteria } from './missing-criteria.ts';
+export { normaliseTitle } from './normalise-title.ts';

package/dist/missing-criteria.d.ts

@@ -0,0 +1,2 @@
+import type { BuildCloseOut, CriterionId, EvidenceRow, ItemView } from '@boxxy/model';
+export declare function missingCriteria(item: ItemView, evidence: readonly EvidenceRow[], cited: BuildCloseOut['criteria']): readonly CriterionId[];

package/dist/normalise-title.d.ts

@@ -0,0 +1 @@
+export declare function normaliseTitle(title: string): string;

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@boxxy/closeout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "boxxy's close-out parser: checks the close-out an agent sends at the end of an attempt",
+  "homepage": "https://github.com/zgeoff/boxxy/tree/main/modules/closeout#readme",
+  "bugs": "https://github.com/zgeoff/boxxy/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zgeoff/boxxy.git",
+    "directory": "modules/closeout"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsrs -p tsconfig.build.json",
+    "typecheck": "tsrs --noEmit"
+  },
+  "dependencies": {
+    "@boxxy/model": "0.1.1",
+    "tiny-invariant": "1.3.3"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  }
+}

package/src/build-close-out-parser.ts

@@ -0,0 +1,115 @@
+import type {
+  BuildCloseOut,
+  CloseOutContext,
+  CloseOutParse,
+  CloseOutParser,
+  CloseOutProblem,
+} from '@boxxy/model';
+import { buildCloseOutSchema, formatKeyPath } from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { missingCriteria } from './missing-criteria.ts';
+
+export const buildCloseOutParser: CloseOutParser<BuildCloseOut> = { parse: parseBuildCloseOut };
+
+function parseBuildCloseOut(raw: unknown, ctx: CloseOutContext): CloseOutParse<BuildCloseOut> {
+  const split = splitFriction(raw);
+  const parsed = buildCloseOutSchema.safeParse(split.candidate);
+
+  if (!parsed.success) {
+    return {
+      kind: 'invalid',
+      problems: parsed.error.issues.map((issue) => buildSchemaProblem(issue, split.keptRawIndexes)),
+    };
+  }
+
+  const problems = collectProblems(parsed.data, ctx);
+
+  return problems.length === 0
+    ? { kind: 'valid', closeOut: parsed.data }
+    : { kind: 'invalid', problems };
+}
+
+interface FrictionSplit {
+  readonly candidate: unknown;
+  readonly keptRawIndexes: readonly number[];
+}
+
+function splitFriction(raw: unknown): FrictionSplit {
+  if (!isRecord(raw)) {
+    return { candidate: raw, keptRawIndexes: [] };
+  }
+
+  const entries: readonly unknown[] = Array.isArray(raw['friction']) ? raw['friction'] : [];
+  const keptRawIndexes = entries.flatMap((entry, index) => (isUntargeted(entry) ? [] : [index]));
+
+  const friction = Array.isArray(raw['friction'])
+    ? keptRawIndexes.map((index) => entries[index])
+    : raw['friction'];
+
+  return {
+    candidate: { ...raw, friction, frictionDropped: entries.length - keptRawIndexes.length },
+    keptRawIndexes,
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isUntargeted(entry: unknown): boolean {
+  return isRecord(entry) && (entry['target'] === undefined || entry['target'] === null);
+}
+
+interface SchemaIssue {
+  readonly path: readonly PropertyKey[];
+  readonly message: string;
+}
+
+function buildSchemaProblem(
+  issue: SchemaIssue,
+  keptRawIndexes: readonly number[],
+): CloseOutProblem {
+  return {
+    kind: 'schema',
+    path: formatKeyPath(toRawPath(issue.path, keptRawIndexes)),
+    message: issue.message,
+  };
+}
+
+function toRawPath(path: readonly PropertyKey[], keptRawIndexes: readonly number[]): PropertyKey[] {
+  const [field, index, ...rest] = path;
+
+  if (field !== 'friction' || typeof index !== 'number') {
+    return [...path];
+  }
+
+  const rawIndex = keptRawIndexes[index];
+
+  invariant(rawIndex !== undefined, 'a friction issue points at an entry the parser kept');
+
+  return [field, rawIndex, ...rest];
+}
+
+function collectProblems(closeOut: BuildCloseOut, ctx: CloseOutContext): CloseOutProblem[] {
+  const acceptance = new Set(ctx.item.acceptance.map((criterion) => criterion.id));
+  const own = new Set(ctx.evidence.map((row) => row.factId));
+
+  const cited = closeOut.criteria;
+
+  const unknownCriteria = new Set(
+    cited.map((entry) => entry.criterion).filter((id) => !acceptance.has(id)),
+  );
+
+  const foreignEvidence = new Set(
+    cited.map((entry) => entry.evidence).filter((id) => !own.has(id)),
+  );
+
+  const missing =
+    closeOut.result.kind === 'built' ? missingCriteria(ctx.item, ctx.evidence, cited) : [];
+
+  return [
+    ...[...unknownCriteria].map((criterion) => ({ kind: 'unknown-criterion' as const, criterion })),
+    ...[...foreignEvidence].map((evidence) => ({ kind: 'foreign-evidence' as const, evidence })),
+    ...(missing.length > 0 ? [{ kind: 'built-without-evidence' as const, criteria: missing }] : []),
+  ];
+}

package/src/dedupe-open-items.ts

@@ -0,0 +1,47 @@
+import type { ItemId, ItemView, OpenItem } from '@boxxy/model';
+import { normaliseTitle } from './normalise-title.ts';
+
+export function dedupeOpenItems(
+  entries: readonly OpenItem[],
+  open: readonly ItemView[],
+): { readonly file: readonly OpenItem[]; readonly matched: readonly ItemId[] } {
+  const openByTitle = collectOpenByTitle(open);
+  const matched = entries.flatMap((entry) => openByTitle.get(normaliseTitle(entry.title)) ?? []);
+
+  return { file: collectNewEntries(entries, openByTitle), matched: [...new Set(matched)] };
+}
+
+function collectOpenByTitle(open: readonly ItemView[]): Map<string, ItemId> {
+  const openByTitle = new Map<string, ItemId>();
+
+  for (const item of open) {
+    const title = normaliseTitle(item.title);
+
+    if (!openByTitle.has(title)) {
+      openByTitle.set(title, item.id);
+    }
+  }
+
+  return openByTitle;
+}
+
+function collectNewEntries(
+  entries: readonly OpenItem[],
+  openByTitle: ReadonlyMap<string, ItemId>,
+): OpenItem[] {
+  const seen = new Set<string>();
+
+  const file: OpenItem[] = [];
+
+  for (const entry of entries) {
+    const title = normaliseTitle(entry.title);
+
+    if (!openByTitle.has(title) && !seen.has(title)) {
+      file.push(entry);
+    }
+
+    seen.add(title);
+  }
+
+  return file;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { buildCloseOutParser } from './build-close-out-parser.ts';
+export { dedupeOpenItems } from './dedupe-open-items.ts';
+export { missingCriteria } from './missing-criteria.ts';
+export { normaliseTitle } from './normalise-title.ts';

package/src/missing-criteria.ts

@@ -0,0 +1,15 @@
+import type { BuildCloseOut, CriterionId, EvidenceRow, ItemView } from '@boxxy/model';
+
+export function missingCriteria(
+  item: ItemView,
+  evidence: readonly EvidenceRow[],
+  cited: BuildCloseOut['criteria'],
+): readonly CriterionId[] {
+  const known = new Set(evidence.map((row) => row.factId));
+
+  const met = new Set(
+    cited.filter((entry) => known.has(entry.evidence)).map((entry) => entry.criterion),
+  );
+
+  return item.acceptance.map((criterion) => criterion.id).filter((id) => !met.has(id));
+}

package/src/normalise-title.ts

@@ -0,0 +1,3 @@
+export function normaliseTitle(title: string): string {
+  return title.trim().toLowerCase().replaceAll(/\s+/gu, ' ');
+}