@withtruing/companion 0.13.3 → 0.14.0

package/dist/whole-read/notes.js

@@ -0,0 +1,216 @@
+import { createHash } from 'node:crypto';
+export const READ_CARDS_SCHEMA_VERSION = 'whole-read-cards@1';
+export const READ_NOTES_SCHEMA_VERSION = READ_CARDS_SCHEMA_VERSION;
+export class ReadNoteValidationError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'ReadNoteValidationError';
+    }
+}
+const textSchema = { type: 'string', minLength: 1 };
+const cardSchema = {
+    type: 'object', additionalProperties: false, required: ['item', 'summary', 'kind'],
+    properties: {
+        item: { type: 'integer', minimum: 1 },
+        summary: { type: 'string', minLength: 1, maxLength: 300 },
+        kind: { type: 'string', enum: ['product', 'test', 'tooling', 'config', 'docs', 'infrastructure'] },
+        usesHint: { type: 'array', maxItems: 20, items: { ...textSchema, maxLength: 120 } },
+    },
+};
+/** Strict model-output schema. Cards contain no evidence, identity, or provenance fields. */
+export const readCardsSchema = {
+    type: 'object', additionalProperties: false, required: ['cards'],
+    properties: { cards: { type: 'array', items: cardSchema } },
+};
+export const readNotesSchema = readCardsSchema;
+const CARD_KEYS = new Set(['item', 'summary', 'kind', 'usesHint']);
+const KINDS = new Set(['product', 'test', 'tooling', 'config', 'docs', 'infrastructure']);
+const fail = (code) => { throw new ReadNoteValidationError(code); };
+const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const nonBlank = (value) => typeof value === 'string' && value.trim().length > 0;
+const positive = (value) => Number.isSafeInteger(value) && value >= 1;
+function parseResult(value) {
+    if (!record(value) || Object.keys(value).length !== 1 || !Array.isArray(value.cards)) {
+        return fail('note_schema_invalid');
+    }
+    for (const card of value.cards) {
+        if (!record(card) || Object.keys(card).some((key) => !CARD_KEYS.has(key))
+            || !positive(card.item) || !nonBlank(card.summary) || Array.from(card.summary).length > 300
+            || !KINDS.has(card.kind)
+            || (Object.hasOwn(card, 'usesHint') && (!Array.isArray(card.usesHint) || card.usesHint.length > 20
+                || card.usesHint.some((hint) => !nonBlank(hint) || Array.from(hint).length > 120)))) {
+            return fail('note_schema_invalid');
+        }
+        if (!['item', 'summary', 'kind'].every((key) => Object.hasOwn(card, key)))
+            fail('note_schema_invalid');
+    }
+    return value.cards;
+}
+const extension = (path) => {
+    const name = path.replaceAll('\\', '/').split('/').at(-1).toLowerCase();
+    const dot = name.lastIndexOf('.');
+    return dot < 0 ? '' : name.slice(dot);
+};
+/** Returns only mechanically obvious path classifications; everything else stays model-authored. */
+export function kindFromPath(path) {
+    const normalized = path.replaceAll('\\', '/').replace(/^\.\//, '').toLowerCase();
+    const parts = normalized.split('/').filter(Boolean);
+    const name = parts.at(-1) ?? '';
+    const ext = extension(normalized);
+    if (parts.some((part) => ['test', 'tests', '__tests__', 'spec', 'specs'].includes(part))
+        || /(?:^|\.)(?:test|spec)\.[^.]+$/.test(name))
+        return { kind: 'test', rule: 'test path or filename' };
+    if (parts.some((part) => ['docs', 'doc', 'documentation'].includes(part))
+        || ['.md', '.mdx', '.rst', '.adoc', '.asciidoc'].includes(ext)
+        || /^(readme|changelog|contributing|license)(?:\.|$)/.test(name)) {
+        return { kind: 'docs', rule: 'documentation path or extension' };
+    }
+    if (normalized.startsWith('.github/workflows/') || parts.some((part) => ['terraform', 'kubernetes', 'k8s', 'infrastructure', 'infra', 'deploy'].includes(part))
+        || ['.tf', '.tfvars'].includes(ext) || /^dockerfile(?:\.|$)/.test(name)
+        || /^(docker-compose|compose)\.(?:ya?ml)$/.test(name)) {
+        return { kind: 'infrastructure', rule: 'infrastructure path or extension' };
+    }
+    const genericDataExtension = ['.json', '.jsonc', '.yaml', '.yml', '.toml'].includes(ext);
+    const configurationFilename = /(?:^|\.)(?:config|rc)\.[^.]+$/.test(name)
+        || /^(package|tsconfig|jsconfig|eslint|prettier|babel|vite|vitest|jest|playwright)\./.test(name)
+        || /^\.[a-z0-9_-]+rc(?:\.[a-z0-9]+)?$/.test(name);
+    if (['.ini', '.cfg', '.conf'].includes(ext) || configurationFilename
+        || (genericDataExtension && (parts.length === 1
+            || parts.some((part) => ['config', 'configs', '.config', 'settings', 'conf'].includes(part))))) {
+        return { kind: 'config', rule: 'configuration filename or extension' };
+    }
+    if (parts.some((part) => ['scripts', 'script', 'tools', 'tooling'].includes(part))
+        || ['.sh', '.bash', '.zsh', '.fish', '.ps1', '.bat', '.cmd'].includes(ext)
+        || /^(makefile|justfile|rakefile)$/.test(name)) {
+        return { kind: 'tooling', rule: 'tooling path or extension' };
+    }
+    return null;
+}
+export function importResolverCoversPath(path) {
+    return ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts'].includes(extension(path));
+}
+function noteId(item) {
+    const identity = `${item.item.entryId}\0${item.item.inventoryRevision}\0${item.item.path}`
+        + `\0${item.item.primarySpan.startByte}:${item.item.primarySpan.endByte}`;
+    return `note_${createHash('sha256').update(identity, 'utf8').digest('hex').slice(0, 24)}`;
+}
+function displaySpan(span, expected) {
+    const primary = expected.item.primarySpan;
+    if (!Number.isSafeInteger(span.startByte) || !Number.isSafeInteger(span.endByte)
+        || span.startByte < primary.startByte || span.endByte > primary.endByte
+        || span.endByte <= span.startByte)
+        return fail('note_span_invalid');
+    const start = expected.decoded.mapping.lines.find((line) => span.startByte >= line.startByte && span.startByte < line.endByte);
+    const end = expected.decoded.mapping.lines.find((line) => span.endByte - 1 >= line.startByte && span.endByte - 1 < line.endByte);
+    if (!start || !end)
+        return fail('note_span_invalid');
+    return { ...span, startLine: start.lineNumber, endLine: end.lineNumber };
+}
+/** Validates strict cards, exact sent-item membership, path kinds, and Truing-derived uses. */
+export function validateReadNotes(input) {
+    const cards = parseResult(input.result);
+    const expected = new Map();
+    const identities = new Set();
+    input.items.forEach((item, index) => {
+        const identity = `${item.item.entryId}\0${item.item.primarySpan.startByte}:${item.item.primarySpan.endByte}`;
+        if (!item.item.path || identities.has(identity))
+            throw new TypeError('note_validation_input_invalid');
+        identities.add(identity);
+        expected.set(index + 1, item);
+    });
+    const supplied = new Map();
+    for (const card of cards) {
+        if (supplied.has(card.item))
+            fail('note_membership_invalid');
+        supplied.set(card.item, card);
+    }
+    if (supplied.size !== expected.size || [...supplied.keys()].some((key) => !expected.has(key))) {
+        fail('note_membership_invalid');
+    }
+    const targetByPath = new Map();
+    const pathByTarget = new Map();
+    for (const target of input.inventory) {
+        if (!target.path || !target.entryId || targetByPath.has(target.path) || pathByTarget.has(target.entryId)) {
+            throw new TypeError('note_validation_input_invalid');
+        }
+        targetByPath.set(target.path, target.entryId);
+        pathByTarget.set(target.entryId, target.path);
+    }
+    return { notes: [...expected].map(([key, item]) => {
+            const card = supplied.get(key);
+            const pathRule = kindFromPath(item.item.path);
+            if (card.usesHint !== undefined && importResolverCoversPath(item.item.path))
+                fail('note_schema_invalid');
+            const kind = pathRule?.kind ?? card.kind;
+            const kindSource = pathRule
+                ? { source: 'path_rule', rule: pathRule.rule } : { source: 'index_card', rule: null };
+            const fullSpan = displaySpan(item.item.primarySpan, item);
+            const uses = input.importEdges
+                .filter((edge) => edge.sourceEntryId === item.item.entryId
+                && edge.sourceSpan.startByte >= item.item.primarySpan.startByte
+                && edge.sourceSpan.endByte <= item.item.primarySpan.endByte
+                && pathByTarget.has(edge.targetEntryId))
+                .map((edge) => ({
+                target: pathByTarget.get(edge.targetEntryId), span: displaySpan(edge.sourceSpan, item),
+                classification: 'established_import', targetEntryId: edge.targetEntryId, dependency: null,
+            }));
+            for (const hint of card.usesHint ?? []) {
+                const targetEntryId = targetByPath.get(hint) ?? null;
+                uses.push({ target: hint, span: null, classification: targetEntryId ? 'candidate' : 'unvalidated',
+                    targetEntryId, dependency: null });
+            }
+            return { path: item.item.path, blobId: item.item.blobId, range: { ...item.item.primarySpan },
+                summary: card.summary, kind, kindSource,
+                kindReason: { text: pathRule ? `path rule: ${pathRule.rule}` : 'from index card', span: fullSpan },
+                facts: [], exposes: [], uses, noteId: noteId(item), entryId: item.item.entryId,
+                inventoryRevision: item.item.inventoryRevision };
+        }) };
+}
+/** Removes no child data; ordinal is scoped by note id and child kind. */
+export function normalizeReadNotes(value) {
+    const notes = [];
+    const children = [];
+    for (const { facts, exposes, uses, ...note } of value.notes) {
+        notes.push(note);
+        facts.forEach((fact, ordinal) => children.push({ noteId: note.noteId, childKind: 'fact', ordinal, ...fact }));
+        exposes.forEach((expose, ordinal) => children.push({ noteId: note.noteId, childKind: 'expose', ordinal, ...expose }));
+        uses.forEach((use, ordinal) => children.push({ noteId: note.noteId, childKind: 'use', ordinal, ...use }));
+    }
+    return { notes, children };
+}
+/** Inverse of normalizeReadNotes; rejects missing, duplicate, or non-contiguous child ordinals. */
+export function reassembleReadNotes(value) {
+    const ids = new Set(value.notes.map((note) => note.noteId));
+    if (ids.size !== value.notes.length)
+        throw new TypeError('normalized_notes_invalid');
+    const grouped = new Map();
+    for (const child of value.children) {
+        if (!ids.has(child.noteId) || !['fact', 'expose', 'use'].includes(child.childKind)
+            || !Number.isSafeInteger(child.ordinal) || child.ordinal < 0
+            || (child.childKind === 'use' && child.classification.startsWith('established_') && !child.span)) {
+            throw new TypeError('normalized_notes_invalid');
+        }
+        const key = `${child.noteId}\0${child.childKind}`;
+        const found = grouped.get(key) ?? [];
+        if (found.some((candidate) => candidate.ordinal === child.ordinal))
+            throw new TypeError('normalized_notes_invalid');
+        found.push(child);
+        grouped.set(key, found);
+    }
+    const children = (noteId, kind) => {
+        const found = (grouped.get(`${noteId}\0${kind}`) ?? []).sort((left, right) => left.ordinal - right.ordinal);
+        if (found.some((child, ordinal) => child.ordinal !== ordinal))
+            throw new TypeError('normalized_notes_invalid');
+        return found;
+    };
+    return { notes: value.notes.map((note) => ({ ...note,
+            facts: children(note.noteId, 'fact')
+                .map(({ noteId: _id, childKind: _kind, ordinal: _ordinal, ...fact }) => fact),
+            exposes: children(note.noteId, 'expose')
+                .map(({ noteId: _id, childKind: _kind, ordinal: _ordinal, ...expose }) => expose),
+            uses: children(note.noteId, 'use')
+                .map(({ noteId: _id, childKind: _kind, ordinal: _ordinal, ...use }) => use),
+        })) };
+}

package/dist/whole-read/npm-proof.js

@@ -0,0 +1,272 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { Readable, Transform } from 'node:stream';
+import { createGunzip } from 'node:zlib';
+const require = createRequire(import.meta.url);
+const tar = require('tar-stream');
+const REGISTRY_ORIGIN = 'https://registry.npmjs.org';
+const COMPRESSED_LIMIT = 64 * 1024 * 1024;
+const INSPECTED_LIMIT = 256 * 1024 * 1024;
+const MEMBER_LIMIT = 100_000;
+const RULES_VERSION = 'npm-proof@1';
+const PACKAGE_NAME = /^(?:@[^/@\s]+\/)?[^/@\s]+$/;
+const SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const readResult = (reason) => ({ kind: 'read', reason });
+function validIdentity(name, version) {
+    return typeof name === 'string' && typeof version === 'string'
+        && PACKAGE_NAME.test(name) && SEMVER.test(version);
+}
+function strictUtf8(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes).replace(/^\uFEFF/, '');
+    }
+    catch {
+        return null;
+    }
+}
+function parsePackageJson(bytes) {
+    const text = strictUtf8(bytes);
+    if (text === null)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        const record = parsed;
+        return validIdentity(record.name, record.version)
+            ? { name: record.name, version: record.version }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function safeRepositoryPath(path) {
+    return path.length > 0 && !path.startsWith('/') && !path.includes('\\')
+        && path.split('/').every((part) => part.length > 0 && part !== '.' && part !== '..');
+}
+function packageIdentity(input) {
+    try {
+        if (!safeRepositoryPath(input.path))
+            return null;
+        const parts = input.path.split('/');
+        for (let length = parts.length; length > 0; length -= 1) {
+            const root = parts.slice(0, length - 1).join('/');
+            const manifestPath = root.length === 0 ? 'package.json' : `${root}/package.json`;
+            const manifest = manifestPath === input.path ? input.bytes : input.getFile(manifestPath);
+            if (manifest === null)
+                continue;
+            const parsed = parsePackageJson(manifest);
+            if (parsed === null)
+                return null;
+            return { ...parsed, root };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function relativePackagePath(path, root) {
+    const relative = root.length === 0 ? path : path.slice(root.length + 1);
+    return safeRepositoryPath(relative) ? relative : null;
+}
+function metadataUrl(name, version) {
+    return `${REGISTRY_ORIGIN}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`;
+}
+function expectedTarballUrl(name, version) {
+    const leaf = name.includes('/') ? name.slice(name.lastIndexOf('/') + 1) : name;
+    return `${REGISTRY_ORIGIN}/${name}/-/${leaf}-${version}.tgz`;
+}
+function verifiedIntegrity(integrity, bytes) {
+    if (typeof integrity !== 'string')
+        return false;
+    const match = /^sha(256|384|512)-([A-Za-z0-9+/]+={0,2})$/.exec(integrity);
+    if (match === null)
+        return false;
+    const expected = Buffer.from(match[2], 'base64');
+    const actual = createHash(`sha${match[1]}`).update(bytes).digest();
+    return expected.length === actual.length && timingSafeEqual(expected, actual);
+}
+async function boundedFetch(transport, url) {
+    try {
+        const bytes = await transport.fetchRegistry(url);
+        return bytes instanceof Uint8Array && bytes.byteLength <= COMPRESSED_LIMIT ? bytes : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchArtifact(name, version, transport) {
+    const metadataBytes = await boundedFetch(transport, metadataUrl(name, version));
+    const metadataText = metadataBytes === null ? null : strictUtf8(metadataBytes);
+    if (metadataText === null)
+        return null;
+    try {
+        const metadata = JSON.parse(metadataText);
+        if (metadata === null || typeof metadata !== 'object' || Array.isArray(metadata))
+            return null;
+        const record = metadata;
+        const dist = record.dist;
+        if (!validIdentity(record.name, record.version) || record.name !== name || record.version !== version
+            || dist === null || typeof dist !== 'object' || Array.isArray(dist))
+            return null;
+        const distRecord = dist;
+        if (distRecord.tarball !== expectedTarballUrl(name, version))
+            return null;
+        const bytes = await boundedFetch(transport, distRecord.tarball);
+        if (bytes === null || !verifiedIntegrity(distRecord.integrity, bytes))
+            return null;
+        return {
+            bytes,
+            integrity: distRecord.integrity,
+            name,
+            tarballSha256: sha256(bytes),
+            version,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function safeArchiveMemberPath(path) {
+    if (!path.startsWith('package/') || path.includes('\\') || path.includes('\0'))
+        return false;
+    return path.split('/').every((part, index, parts) => (index === parts.length - 1 && part.length === 0) || (part.length > 0 && part !== '.' && part !== '..'));
+}
+async function inspectArtifact(bytes) {
+    return new Promise((resolve) => {
+        const source = Readable.from([Buffer.from(bytes)]);
+        const gunzip = createGunzip();
+        const extractor = tar.extract();
+        const members = [];
+        const seen = new Set();
+        let inspected = 0;
+        let memberCount = 0;
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            source.destroy();
+            gunzip.destroy();
+            extractor.destroy();
+            resolve(result);
+        };
+        const fail = (reason) => finish({ ok: false, reason });
+        const counter = new Transform({
+            transform(chunk, _encoding, callback) {
+                inspected += chunk.length;
+                callback(inspected > INSPECTED_LIMIT ? new Error('uncompressed_limit') : null, chunk);
+            },
+        });
+        extractor.on('entry', (header, stream, next) => {
+            memberCount += 1;
+            if (memberCount > MEMBER_LIMIT) {
+                stream.resume();
+                next(new Error('member_limit'));
+                return;
+            }
+            if (!safeArchiveMemberPath(header.name) || seen.has(header.name)
+                || (header.type !== 'file' && header.type !== 'directory')) {
+                stream.resume();
+                next(new Error('unsafe_archive'));
+                return;
+            }
+            seen.add(header.name);
+            const hash = createHash('sha256');
+            stream.on('data', (chunk) => hash.update(chunk));
+            stream.once('error', () => fail('unsafe_archive'));
+            stream.once('end', () => {
+                if (header.type === 'file') {
+                    members.push({ path: header.name.slice('package/'.length), sha256: hash.digest('hex') });
+                }
+                next();
+            });
+        });
+        extractor.on('finish', () => finish({ ok: true, members }));
+        extractor.on('error', (error) => fail(error.message));
+        gunzip.on('error', () => fail('corrupt_artifact'));
+        counter.on('error', (error) => fail(error.message));
+        source.on('error', () => fail('corrupt_artifact'));
+        source.pipe(gunzip).pipe(counter).pipe(extractor);
+    });
+}
+function proof(artifact, pathInPackage, localSha256, registrySha256) {
+    return {
+        ecosystem: 'npm',
+        registry: REGISTRY_ORIGIN,
+        packageName: artifact.name,
+        version: artifact.version,
+        pathInPackage,
+        localSha256,
+        registrySha256,
+        tarballSha256: artifact.tarballSha256,
+        tarballIntegrity: artifact.integrity,
+        rulesVersion: RULES_VERSION,
+    };
+}
+export async function proveNpmEntry(input, registry) {
+    const identity = packageIdentity(input);
+    if (identity === null)
+        return readResult('npm_package_root_unproven');
+    const pathInPackage = relativePackagePath(input.path, identity.root);
+    if (pathInPackage === null)
+        return readResult('npm_package_path_unproven');
+    const artifact = await fetchArtifact(identity.name, identity.version, registry);
+    if (artifact === null)
+        return readResult(`npm_artifact_unproven:${identity.name}@${identity.version}`);
+    let inspection;
+    try {
+        inspection = await inspectArtifact(artifact.bytes);
+    }
+    catch {
+        return readResult(`npm_artifact_unproven:${identity.name}@${identity.version}`);
+    }
+    if (!inspection.ok)
+        return readResult(`npm_artifact_unproven:${inspection.reason}`);
+    const member = inspection.members.find((entry) => entry.path === pathInPackage);
+    if (member === undefined)
+        return readResult(`npm_artifact_member_missing:${identity.name}@${identity.version}`);
+    const localSha256 = sha256(input.bytes);
+    if (localSha256 !== member.sha256)
+        return readResult(`modified copy of ${identity.name}@${identity.version}`);
+    return { kind: 'vendored_identical', proof: proof(artifact, pathInPackage, localSha256, member.sha256) };
+}
+function bannerIdentity(bytes) {
+    const text = strictUtf8(bytes);
+    if (text === null)
+        return null;
+    const match = /(?:\/\*!\s+|@license\s+)(@?[^\s]+)\s+v([^\s*]+)/.exec(text);
+    return match !== null && validIdentity(match[1], match[2]) ? { name: match[1], version: match[2] } : null;
+}
+export async function proveNpmBanner(input, registry) {
+    if (!safeRepositoryPath(input.path))
+        return readResult('npm_banner_path_unproven');
+    const identity = bannerIdentity(input.bytes);
+    if (identity === null)
+        return readResult('npm_banner_not_applicable');
+    const artifact = await fetchArtifact(identity.name, identity.version, registry);
+    if (artifact === null)
+        return readResult(`npm_banner_artifact_unproven:${identity.name}@${identity.version}`);
+    let inspection;
+    try {
+        inspection = await inspectArtifact(artifact.bytes);
+    }
+    catch {
+        return readResult(`npm_banner_artifact_unproven:${identity.name}@${identity.version}`);
+    }
+    if (!inspection.ok)
+        return readResult(`npm_banner_artifact_unproven:${inspection.reason}`);
+    const localSha256 = sha256(input.bytes);
+    const matches = inspection.members.filter((entry) => entry.sha256 === localSha256);
+    if (matches.length !== 1)
+        return readResult(matches.length === 0
+            ? `npm_banner_not_identical:${identity.name}@${identity.version}`
+            : `npm_banner_ambiguous_artifact:${identity.name}@${identity.version}`);
+    return {
+        kind: 'library_banner_identical',
+        proof: proof(artifact, matches[0].path, localSha256, matches[0].sha256),
+    };
+}