@makehash/nocap 0.0.0-stage → 0.1.0

package/dist/infrastructure/markdown/spec-document.markdown.parser.d.ts

@@ -0,0 +1,5 @@
+import type { SpecDocumentParser } from '../../application/spec/spec-document.parser.js';
+import type { SpecTagSite } from '../../domain/spec/spec-tag-site.boundary.js';
+export declare class SpecDocumentMarkdownParser implements SpecDocumentParser {
+    parse(content: string): SpecTagSite[];
+}

package/dist/infrastructure/markdown/spec-document.markdown.parser.js

@@ -0,0 +1,61 @@
+import { fromMarkdown } from 'mdast-util-from-markdown';
+const COMMENT_OPEN = '<!--';
+const COMMENT_CLOSE = '-->';
+export class SpecDocumentMarkdownParser {
+    parse(content) {
+        return listItemsInDocumentOrder(fromMarkdown(content))
+            .flatMap((item) => commentedListItemOf(item) ?? [])
+            .map((commented) => tagSiteOf(commented, content));
+    }
+}
+function listItemsInDocumentOrder(document) {
+    return descendantsOf(document).filter((node) => node.type === 'listItem');
+}
+// A parent comes before its children, which is the order the nodes appear in the document.
+function descendantsOf(node) {
+    const children = 'children' in node ? node.children : [];
+    return children.flatMap((child) => [child, ...descendantsOf(child)]);
+}
+function commentedListItemOf(item) {
+    const paragraph = firstParagraphOf(item);
+    if (paragraph === undefined)
+        return undefined;
+    const comment = trailingCommentOf(paragraph);
+    if (comment === undefined)
+        return undefined;
+    return { item, paragraph, comment };
+}
+function firstParagraphOf(item) {
+    const first = item.children.find((child) => child.type !== 'list');
+    return first?.type === 'paragraph' ? first : undefined;
+}
+function trailingCommentOf(paragraph) {
+    const last = paragraph.children.at(-1);
+    const isComment = last?.type === 'html' && last.value.startsWith(COMMENT_OPEN) && last.value.endsWith(COMMENT_CLOSE);
+    return isComment ? last : undefined;
+}
+function tagSiteOf({ item, paragraph, comment }, content) {
+    return {
+        line: startOf(item).line,
+        text: sentenceOf(paragraph, comment, content),
+        comment: { line: startOf(comment).line, body: commentBodyOf(comment) },
+    };
+}
+function sentenceOf(paragraph, comment, content) {
+    return content
+        .slice(startOf(paragraph).offset, startOf(comment).offset)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line !== '')
+        .join(' ');
+}
+function commentBodyOf(comment) {
+    return comment.value.slice(COMMENT_OPEN.length, -COMMENT_CLOSE.length);
+}
+function startOf(node) {
+    const start = node.position?.start;
+    if (start?.offset === undefined) {
+        throw new Error(`Parsed markdown node has no position: ${node.type}`);
+    }
+    return { line: start.line, offset: start.offset };
+}

package/dist/infrastructure/typescript/test-file.typescript.parser.d.ts

@@ -0,0 +1,4 @@
+import type { TestFileParser, TestFileParseResult } from '../../application/test/test-file.parser.js';
+export declare class TestFileTypescriptParser implements TestFileParser {
+    parse(path: string, content: string): TestFileParseResult;
+}

package/dist/infrastructure/typescript/test-file.typescript.parser.js

@@ -0,0 +1,110 @@
+import { extname } from 'node:path';
+import { parseSync, Visitor } from 'oxc-parser';
+import { isNonEmpty } from '../../lib/array-length.js';
+const LANGUAGE_ENTRIES = [
+    ['.ts', 'ts'],
+    ['.mts', 'ts'],
+    ['.cts', 'ts'],
+    ['.tsx', 'tsx'],
+    ['.js', 'js'],
+    ['.mjs', 'js'],
+    ['.cjs', 'js'],
+    ['.jsx', 'jsx'],
+];
+const SUPPORTED_LANGUAGES = new Map(LANGUAGE_ENTRIES);
+const [[FIRST_EXTENSION], ...OTHER_LANGUAGE_ENTRIES] = LANGUAGE_ENTRIES;
+const SUPPORTED_EXTENSIONS = [FIRST_EXTENSION, ...OTHER_LANGUAGE_ENTRIES.map(([extension]) => extension)];
+const TEST_FUNCTIONS = new Set(['it', 'test', 'describe', 'suite']);
+export class TestFileTypescriptParser {
+    parse(path, content) {
+        const extension = extname(path);
+        const language = SUPPORTED_LANGUAGES.get(extension);
+        if (language === undefined) {
+            return { kind: 'unsupported-extension', extension, supportedExtensions: SUPPORTED_EXTENSIONS };
+        }
+        const { program, comments, errors } = parseSync(path, content, { lang: language });
+        const messages = errors.map((error) => error.message);
+        if (isNonEmpty(messages)) {
+            return { kind: 'syntax-error', messages };
+        }
+        const lines = sourceLinesOf(content);
+        const outermostCalls = outermostCallsByLine(program, lines);
+        const sites = ownLineCommentsOf(comments, lines)
+            .flatMap((comment) => commentedTestCallOf(comment, outermostCalls, lines) ?? [])
+            .map((commented) => tagSiteOf(commented, lines));
+        return { kind: 'parsed', sites };
+    }
+}
+// `test.each([1])('x', fn)` has two calls that start at the same offset. The outer call ends later.
+function outermostCallsByLine(program, lines) {
+    const outermost = new Map();
+    new Visitor({
+        CallExpression: (call) => {
+            const line = lineOf(call, lines);
+            const current = outermost.get(line);
+            if (current === undefined || encloses(call, current))
+                outermost.set(line, call);
+        },
+    }).visit(program);
+    return outermost;
+}
+function encloses(outer, inner) {
+    return outer.start < inner.start || (outer.start === inner.start && outer.end > inner.end);
+}
+function ownLineCommentsOf(comments, lines) {
+    return comments.filter((comment) => comment.type === 'Line' && startsLine(comment, lines));
+}
+function commentedTestCallOf(comment, outermostCalls, lines) {
+    const call = outermostCalls.get(lineOf(comment, lines) + 1);
+    if (call === undefined || !isTestCall(call))
+        return undefined;
+    return { call, comment };
+}
+function isTestCall(call) {
+    const root = rootNameOf(call.callee);
+    return root !== undefined && TEST_FUNCTIONS.has(root);
+}
+function rootNameOf(node) {
+    switch (node.type) {
+        case 'Identifier':
+            return node.name;
+        case 'MemberExpression':
+            return rootNameOf(node.object);
+        case 'CallExpression':
+            return rootNameOf(node.callee);
+        case 'TaggedTemplateExpression':
+            return rootNameOf(node.tag);
+        default:
+            return undefined;
+    }
+}
+function tagSiteOf({ call, comment }, lines) {
+    return {
+        line: lineOf(call, lines),
+        comment: { line: lineOf(comment, lines), body: comment.value },
+    };
+}
+function sourceLinesOf(content) {
+    const starts = [0];
+    for (let newline = content.indexOf('\n'); newline !== -1; newline = content.indexOf('\n', newline + 1)) {
+        starts.push(newline + 1);
+    }
+    return { content, starts };
+}
+function startsLine(node, lines) {
+    const lineStart = lines.starts[lineOf(node, lines) - 1] ?? 0;
+    return lines.content.slice(lineStart, node.start).trim() === '';
+}
+// Binary search for the last line that starts at or before the node.
+function lineOf(node, lines) {
+    let low = 0;
+    let high = lines.starts.length - 1;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if ((lines.starts[middle] ?? Infinity) <= node.start)
+            low = middle;
+        else
+            high = middle - 1;
+    }
+    return low + 1;
+}

package/dist/lib/array-length.d.ts

@@ -0,0 +1,2 @@
+export declare function isNonEmpty<T>(items: readonly T[] | undefined): items is [T, ...T[]];
+export declare function hasTwoOrMore<T>(items: readonly [T, ...T[]]): items is readonly [T, T, ...T[]];

package/dist/lib/array-length.js

@@ -0,0 +1,6 @@
+export function isNonEmpty(items) {
+    return items !== undefined && items.length > 0;
+}
+export function hasTwoOrMore(items) {
+    return items.length >= 2;
+}

package/dist/presentation/cli/coverage-check.command.d.ts

@@ -0,0 +1,19 @@
+import type { CoverageCheckResult, UnmatchedPatterns } from '../../application/coverage/coverage-check.result.js';
+import type { CoverageCheckInput } from '../../application/coverage/coverage-check.usecase.js';
+import type { CoverageCheckTextFormatter } from '../coverage-check.text.formatter.js';
+export type CommandOutput = {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: 0 | 1 | 2;
+};
+type CoverageCheck = {
+    run(input: CoverageCheckInput): Promise<CoverageCheckResult | UnmatchedPatterns>;
+};
+export declare class CoverageCheckCommand {
+    private readonly coverageCheck;
+    private readonly formatter;
+    constructor(coverageCheck: CoverageCheck, formatter: CoverageCheckTextFormatter);
+    run(args: readonly string[]): Promise<CommandOutput>;
+    private parse;
+}
+export {};

package/dist/presentation/cli/coverage-check.command.js

@@ -0,0 +1,51 @@
+import { inspect, parseArgs } from 'node:util';
+import { isNonEmpty } from '../../lib/array-length.js';
+const USAGE = 'Usage: nocap --spec <glob> [--spec <glob> ...] --test <glob> [--test <glob> ...]';
+export class CoverageCheckCommand {
+    coverageCheck;
+    formatter;
+    constructor(coverageCheck, formatter) {
+        this.coverageCheck = coverageCheck;
+        this.formatter = formatter;
+    }
+    async run(args) {
+        const parsed = this.parse(args);
+        if (parsed.kind === 'usage-error')
+            return { stdout: '', stderr: `nocap: ${parsed.message}\n${USAGE}\n`, exitCode: 2 };
+        try {
+            const result = await this.coverageCheck.run(parsed.input);
+            if (result.kind === 'unmatched-patterns')
+                return { stdout: '', stderr: unmatchedPatternsMessage(result), exitCode: 2 };
+            return { ...this.formatter.format(result), exitCode: result.hasProblems() ? 1 : 0 };
+        }
+        catch (error) {
+            return { stdout: '', stderr: internalErrorMessage(error), exitCode: 2 };
+        }
+    }
+    parse(args) {
+        try {
+            const { values } = parseArgs({
+                args: [...args],
+                options: { spec: { type: 'string', multiple: true }, test: { type: 'string', multiple: true } },
+                strict: true,
+                allowPositionals: false,
+            });
+            if (!isNonEmpty(values.spec))
+                return { kind: 'usage-error', message: 'missing --spec' };
+            if (!isNonEmpty(values.test))
+                return { kind: 'usage-error', message: 'missing --test' };
+            return { kind: 'parsed', input: { specPatterns: values.spec, testPatterns: values.test } };
+        }
+        catch (error) {
+            return { kind: 'usage-error', message: error instanceof Error ? error.message : String(error) };
+        }
+    }
+}
+const OPTION_OF_SIDE = { spec: '--spec', test: '--test' };
+function unmatchedPatternsMessage({ patterns }) {
+    return patterns.map(({ side, pattern }) => `nocap: no files match ${OPTION_OF_SIDE[side]} ${JSON.stringify(pattern)}\n`).join('');
+}
+function internalErrorMessage(error) {
+    const detail = error instanceof Error ? `${error.message}\n${inspect(error)}` : inspect(error);
+    return `nocap: internal error: ${detail}\n`;
+}

package/dist/presentation/coverage-check.text.formatter.d.ts

@@ -0,0 +1,16 @@
+import type { CoverageCheckResult } from '../application/coverage/coverage-check.result.js';
+export type ColorSupport = {
+    readonly stdout: boolean;
+    readonly stderr: boolean;
+};
+export type FormattedOutput = {
+    readonly stdout: string;
+    readonly stderr: string;
+};
+export declare class CoverageCheckTextFormatter {
+    private readonly colors;
+    constructor(colors?: ColorSupport);
+    format(result: CoverageCheckResult): FormattedOutput;
+    private stdoutOf;
+    private stderrOf;
+}

package/dist/presentation/coverage-check.text.formatter.js

@@ -0,0 +1,143 @@
+const DIAGNOSTIC_KINDS = [
+    'uncovered-spec',
+    'unknown-id',
+    'duplicate-id',
+    'invalid-id',
+    'missing-id',
+    'multiple-ids',
+    'read-error',
+    'unsupported-extension',
+    'syntax-error',
+];
+const ANSI = { bold: '1', dim: '2', red: '31', green: '32', yellow: '33', cyan: '36' };
+const ID_CHARS_HINT = 'use only A-Z, a-z, 0-9, "-", "_"';
+export class CoverageCheckTextFormatter {
+    colors;
+    constructor(colors = { stdout: false, stderr: false }) {
+        this.colors = colors;
+    }
+    format(result) {
+        const diagnostics = inReportOrder([
+            ...result.coverageProblems.flatMap((problem) => coverageProblemDiagnostics(problem)),
+            ...result.invalidTags.flatMap((invalidTag) => invalidTagDiagnostics(invalidTag)),
+            ...result.fileErrors.flatMap((fileError) => fileErrorDiagnostics(fileError)),
+        ]);
+        return { stdout: this.stdoutOf(diagnostics), stderr: this.stderrOf(diagnostics, result) };
+    }
+    stdoutOf(diagnostics) {
+        const paint = painter(this.colors.stdout);
+        return diagnostics
+            .map((diagnostic, index) => {
+            const samePathAsPrevious = index > 0 && diagnostics[index - 1]?.path === diagnostic.path;
+            const location = paint(samePathAsPrevious ? [ANSI.dim] : [ANSI.cyan], diagnostic.path) +
+                (diagnostic.line === undefined ? '' : `:${paint([ANSI.bold], String(diagnostic.line))}`);
+            const message = diagnostic.message.map((segment) => (segment.isValue ? paint([ANSI.yellow], segment.text) : segment.text)).join('');
+            const hint = diagnostic.hint === undefined ? '' : paint([ANSI.dim], `; hint: ${diagnostic.hint}`);
+            return `${location}: ${paint([ANSI.red, ANSI.bold], 'error')}${paint([ANSI.red], `[${diagnostic.kind}]`)}: ${message}${hint}\n`;
+        })
+            .join('');
+    }
+    stderrOf(diagnostics, result) {
+        const paint = painter(this.colors.stderr);
+        const coverageLine = paint([result.isFullyCovered() ? ANSI.green : ANSI.yellow], `${result.coveredSpecCount} of ${result.specCount} specs covered`);
+        if (diagnostics.length === 0)
+            return `${coverageLine}\n`;
+        return `${paint([ANSI.red, ANSI.bold], errorsLineOf(diagnostics))}\n${coverageLine}\n`;
+    }
+}
+function coverageProblemDiagnostics(problem) {
+    switch (problem.kind) {
+        case 'uncovered-spec': {
+            const text = singleLine(problem.text);
+            const message = [value(problem.id), plain(' has no test'), ...(text === '' ? [] : [plain(`: ${text}`)])];
+            return [diagnosticAt(problem.location, 'uncovered-spec', message)];
+        }
+        case 'unknown-id':
+            return problem.testLocations.map((location) => diagnosticAt(location, 'unknown-id', [value(problem.id), plain(' is not defined in any spec')]));
+        case 'duplicate-id':
+            return problem.specLocations.map((location, index) => {
+                const others = problem.specLocations.filter((_, otherIndex) => otherIndex !== index).map(locationText);
+                return diagnosticAt(location, 'duplicate-id', [value(problem.id), plain(` is also defined at ${others.join(', ')}`)]);
+            });
+    }
+}
+function invalidTagDiagnostics(invalidTag) {
+    switch (invalidTag.kind) {
+        case 'id-rule-violation':
+            return invalidTag.invalidCandidates.map((invalidCandidate) => invalidIdDiagnostic(invalidTag.location, invalidCandidate));
+        case 'missing-id':
+            return [diagnosticAt(invalidTag.location, 'missing-id', [plain('missing id in the tag')], 'write an id, e.g. "nocap: AUTH-001"')];
+        case 'multiple-ids': {
+            const ids = invalidTag.ids.flatMap((id, index) => (index === 0 ? [value(id)] : [plain(', '), value(id)]));
+            const message = [plain(`spec tag has ${invalidTag.ids.length} ids `), ...ids];
+            return [diagnosticAt(invalidTag.location, 'multiple-ids', message, 'a spec item takes 1 id')];
+        }
+    }
+}
+function invalidIdDiagnostic(location, invalidCandidate) {
+    switch (invalidCandidate.kind) {
+        case 'invalid-whitespace':
+            return diagnosticAt(location, 'invalid-id', [value(invalidCandidate.value), plain(' has a space')], 'separate ids with ","');
+        case 'invalid-char':
+            return diagnosticAt(location, 'invalid-id', [value(invalidCandidate.value), plain(' has '), value(invalidCandidate.firstInvalidChar)], ID_CHARS_HINT);
+    }
+}
+function fileErrorDiagnostics(fileError) {
+    switch (fileError.kind) {
+        case 'read-error':
+            return [diagnosticOfFile(fileError.path, 'read-error', [plain(`cannot read file: ${singleLine(fileError.message)}`)])];
+        case 'unsupported-extension':
+            return [
+                diagnosticOfFile(fileError.path, 'unsupported-extension', [value(fileError.extension), plain(' is not a supported test file extension')], `use ${choicesOf(fileError.supportedExtensions)}`),
+            ];
+        case 'syntax-error':
+            return fileError.messages.map((message) => diagnosticOfFile(fileError.path, 'syntax-error', [plain(singleLine(message))]));
+    }
+}
+function errorsLineOf(diagnostics) {
+    const fileCount = new Set(diagnostics.map((diagnostic) => diagnostic.path)).size;
+    const kindCounts = DIAGNOSTIC_KINDS.map((kind) => ({
+        kind,
+        count: diagnostics.filter((diagnostic) => diagnostic.kind === kind).length,
+    }))
+        .filter(({ count }) => count > 0)
+        .map(({ kind, count }) => `${count} ${kind}`);
+    return `${countOf(diagnostics.length, 'error')} in ${countOf(fileCount, 'file')}: ${kindCounts.join(', ')}`;
+}
+function diagnosticAt(location, kind, message, hint) {
+    return { path: location.path, line: location.line, kind, message, hint };
+}
+function diagnosticOfFile(path, kind, message, hint) {
+    return { path, line: undefined, kind, message, hint };
+}
+function inReportOrder(diagnostics) {
+    return [...diagnostics].sort((a, b) => {
+        if (a.path !== b.path)
+            return a.path < b.path ? -1 : 1;
+        return (a.line ?? 0) - (b.line ?? 0);
+    });
+}
+function value(text) {
+    return { text: JSON.stringify(text), isValue: true };
+}
+function plain(text) {
+    return { text, isValue: false };
+}
+function singleLine(text) {
+    return text.replace(/\r\n|\r|\n/g, ' ');
+}
+function locationText(location) {
+    return `${location.path}:${location.line}`;
+}
+function countOf(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+function painter(enabled) {
+    return (codes, text) => (enabled ? `\u001b[${codes.join(';')}m${text}\u001b[0m` : text);
+}
+function choicesOf([first, ...rest]) {
+    const last = rest.at(-1);
+    if (last === undefined)
+        return first;
+    return `${[first, ...rest.slice(0, -1)].join(', ')} or ${last}`;
+}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@makehash/nocap",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Link spec docs to tests, and track which specs are not verified yet",
+  "keywords": [
+    "spec",
+    "coverage",
+    "traceability",
+    "requirements",
+    "testing",
+    "markdown",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "hash_kim",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/makeUgreat/nocap.git",
+    "directory": "packages/nocap"
+  },
+  "homepage": "https://github.com/makeUgreat/nocap#readme",
+  "bugs": "https://github.com/makeUgreat/nocap/issues",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "nocap": "dist/bin.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "lint:deps": "depcruise src --config dependency-cruiser/config.ts",
+    "lint:package": "publint && attw --pack . --profile esm-only"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@swc/core": "^1.16.21",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^22.20.5",
+    "dependency-cruiser": "^18.7.0",
+    "publint": "^0.3.25",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "dependencies": {
+    "mdast-util-from-markdown": "^2.1.0",
+    "oxc-parser": "^0.156.0",
+    "tinyglobby": "^0.2.17"
+  }
+}