@popoverai/dotrequirements 0.23.0 → 0.24.0

package/dist/requirements/index.js

@@ -0,0 +1,174 @@
+import * as path from "node:path";
+import { glob, globSync } from "glob";
+import { buildRequirementMarkdown, getAllRequirements, parseRequirementsFile, parseRequirementsFromFile, } from "../schema/index.js";
+/**
+ * Glob pattern matching *.requirements.md files.
+ */
+const REQUIREMENTS_FILE_PATTERN = "**/*.requirements.md";
+/**
+ * Directories ignored when discovering requirements files.
+ * Shared between async and sync discovery so the two never drift.
+ */
+const REQUIREMENTS_IGNORE_PATTERNS = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/.git/**",
+    "**/build/**",
+    // Exclude example and test fixture directories
+    "**/example/**",
+    "**/examples/**",
+    "**/__tests__/**",
+    "**/fixtures/**",
+    "**/.fixtures/**",
+];
+/**
+ * Find all *.requirements.md files in the workspace.
+ * Supports both .requirements/ directories and colocated files.
+ * Excludes example files, test fixtures, and build artifacts.
+ */
+export async function findRequirementsFiles(workspaceRoot) {
+    const matches = await glob(REQUIREMENTS_FILE_PATTERN, {
+        cwd: workspaceRoot,
+        ignore: REQUIREMENTS_IGNORE_PATTERNS,
+        dot: true, // Include dotfiles/dotdirs like .requirements/
+    });
+    return matches.map((m) => path.join(workspaceRoot, m));
+}
+/**
+ * Synchronous variant of {@link findRequirementsFiles}. Used by code paths
+ * that can't await (e.g. the test-harness lookup-cache builder).
+ */
+export function findRequirementsFilesSync(workspaceRoot) {
+    const matches = globSync(REQUIREMENTS_FILE_PATTERN, {
+        cwd: workspaceRoot,
+        ignore: REQUIREMENTS_IGNORE_PATTERNS,
+        dot: true,
+    });
+    return matches.map((m) => path.join(workspaceRoot, m));
+}
+/**
+ * Load all requirements from the workspace
+ */
+export async function loadAllRequirements(workspaceRoot) {
+    const filePaths = await findRequirementsFiles(workspaceRoot);
+    const allFiles = [];
+    const allFlattened = [];
+    for (const filePath of filePaths) {
+        try {
+            const parsed = parseRequirementsFromFile(filePath);
+            allFiles.push(parsed);
+            const flattened = flattenRequirementsFile(parsed, filePath);
+            allFlattened.push(...flattened);
+        }
+        catch (error) {
+            // Skip invalid files
+            console.error(`Failed to parse ${filePath}:`, error);
+        }
+    }
+    return { files: allFiles, flattened: allFlattened };
+}
+/**
+ * Flatten a requirements file into searchable requirements
+ */
+export function flattenRequirementsFile(file, sourceFile) {
+    const results = [];
+    // Use shared utility to get all requirements (flattened)
+    const allReqs = getAllRequirements(file.requirements);
+    for (const req of allReqs) {
+        // Extract position from ID (e.g., "REQ123.0.1" -> "0.1")
+        const idParts = req.id.split(".");
+        const rootId = idParts[0];
+        results.push({
+            id: req.id,
+            rootId: rootId,
+            label: req.label,
+            content: req.content,
+            path: idParts.slice(1), // ["0", "1"] for "REQ123.0.1"
+            sourceFile: sourceFile,
+            documentTitle: file.metadata.document?.title || rootId,
+        });
+    }
+    return results;
+}
+/**
+ * Search requirements by text query
+ */
+export function searchRequirements(requirements, query) {
+    const lowerQuery = query.toLowerCase();
+    return requirements.filter((req) => {
+        // Search in ID
+        if (req.id.toLowerCase().includes(lowerQuery))
+            return true;
+        // Search in content
+        if (req.content.toLowerCase().includes(lowerQuery))
+            return true;
+        // Search in label
+        if (req.label.toLowerCase().includes(lowerQuery))
+            return true;
+        return false;
+    });
+}
+/**
+ * Get a specific requirement by ID (supports partial matching)
+ */
+export function getRequirementById(requirements, id) {
+    // Exact match first
+    const exact = requirements.find((r) => r.id === id);
+    if (exact)
+        return exact;
+    // Try partial match (just the root ID)
+    return requirements.find((r) => r.rootId === id || r.id.startsWith(`${id}.`));
+}
+/**
+ * Get a requirement and all its children
+ */
+export function getRequirementTree(requirements, rootId) {
+    return requirements.filter((r) => r.rootId === rootId || r.id === rootId);
+}
+/**
+ * Format a requirement for display
+ */
+export function formatRequirement(req) {
+    const indent = "  ".repeat(req.path.length);
+    const label = req.label ? ` (${req.label})` : "";
+    return `${indent}${req.id}${label}: ${req.content}`;
+}
+/**
+ * Filter a requirements file's content to only include specified requirement keys.
+ * Parses the file content, filters top-level requirements by key, and rebuilds as
+ * markdown requirement blocks (without frontmatter).
+ */
+export function filterRequirementsByKeys(fileContents, keys) {
+    const { requirements } = parseRequirementsFile(fileContents);
+    const upperKeys = keys.map((k) => k.toUpperCase());
+    const filtered = requirements.filter((r) => upperKeys.includes(r.id.toUpperCase()));
+    const foundKeys = filtered.map((r) => r.id);
+    const missingKeys = upperKeys.filter((k) => !foundKeys.map((f) => f.toUpperCase()).includes(k));
+    const filteredContent = filtered.map(buildRequirementMarkdown).join("\n");
+    return { filteredContent, foundKeys, missingKeys };
+}
+/**
+ * Format a requirement tree for display
+ */
+export function formatRequirementTree(requirements) {
+    // Sort by path to maintain hierarchy - children appear immediately after parent
+    const sorted = [...requirements].sort((a, b) => {
+        // Compare paths element by element for proper tree order
+        const maxLen = Math.max(a.path.length, b.path.length);
+        for (let i = 0; i < maxLen; i++) {
+            const aVal = i < a.path.length ? parseInt(a.path[i], 10) : -1;
+            const bVal = i < b.path.length ? parseInt(b.path[i], 10) : -1;
+            // If one path is a prefix of the other, the shorter one comes first
+            if (aVal === -1)
+                return -1;
+            if (bVal === -1)
+                return 1;
+            if (aVal !== bVal) {
+                return aVal - bVal;
+            }
+        }
+        return 0;
+    });
+    return sorted.map(formatRequirement).join("\n");
+}
+//# sourceMappingURL=index.js.map

package/dist/requirements/style-guide.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Style-guide template generator. Produces the markdown document that both
+ * the MCP `create_requirement_document` tool and the CLI
+ * `dotreq create-requirement-document` verb return.
+ *
+ * The output is a full ready-to-paste-into-a-PR markdown document that
+ * describes the requirements format, embeds a worked example, and includes
+ * style principles for writing requirements and tests. Discovered label /
+ * key patterns from the calling workspace and (optional) project-owner-
+ * supplied custom guidance are interpolated into the body.
+ *
+ * If the project has a `.requirements/STYLE.md`, callers can pass its
+ * contents via `localStyleGuide` to use that body in place of the bundled
+ * defaults. See {@link readLocalStyleGuide} for the lookup helper.
+ */
+import type { FlattenedRequirement } from "./index.js";
+/**
+ * Conventional location of a project's STYLE.md, relative to the workspace
+ * root. Exported so callers (init, push/pull, tests) can reference one place.
+ */
+export declare const STYLE_MD_PATH = ".requirements/STYLE.md";
+export interface GenerateStyleGuideParams {
+    /** Flattened view of the workspace's existing requirements, used to
+     * surface label patterns and key-prefix patterns in the output. Pass
+     * an empty array when no requirements exist yet. */
+    requirements: FlattenedRequirement[];
+    /** Project-owner-supplied custom guidance (currently sourced from the
+     * cloud project's `requirementsStyleContext` field). Pass null/undefined
+     * to omit. */
+    customStyleGuidance?: string | null;
+    /** Suggested target path for the new file. Used only in the preamble
+     * and "Next Steps" section. Defaults to a generic example path. */
+    filePath?: string;
+    /** Project-local STYLE.md contents. When provided and non-empty, this
+     * body replaces the bundled default; callers can fetch it via
+     * {@link readLocalStyleGuide}. */
+    localStyleGuide?: string | null;
+}
+/**
+ * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
+ * contents on success, `null` if the file is absent. Empty / whitespace-only
+ * files are treated as absent so the bundled defaults still apply.
+ */
+export declare function readLocalStyleGuide(workspaceRoot: string): string | null;
+/**
+ * Build the body of the bundled default style guide. This is the content
+ * that lives inside the "# Requirements File Template" preamble — the
+ * format syntax, key/label conventions, style principles, and example
+ * requirements — with discovered patterns and custom guidance interpolated.
+ *
+ * Exposed separately from {@link generateStyleGuide} so callers can:
+ * - scaffold `.requirements/STYLE.md` with the bundled defaults at init time
+ * - swap the body wholesale (via `localStyleGuide`) without losing the
+ *   wrapping preamble + "Next Steps" footer
+ */
+export declare function generateStyleGuideBody(params: Omit<GenerateStyleGuideParams, "filePath" | "localStyleGuide">): string;
+/**
+ * Build a complete style-guide document for the calling workspace.
+ * Returns a single markdown string suitable for printing to stdout or
+ * wrapping in an MCP text response.
+ *
+ * When `localStyleGuide` is provided and non-empty, that content replaces
+ * the bundled default body. The preamble and "Next Steps" footer are
+ * always applied.
+ */
+export declare function generateStyleGuide(params: GenerateStyleGuideParams): string;
+//# sourceMappingURL=style-guide.d.ts.map

package/dist/requirements/style-guide.js

@@ -0,0 +1,299 @@
+/**
+ * Style-guide template generator. Produces the markdown document that both
+ * the MCP `create_requirement_document` tool and the CLI
+ * `dotreq create-requirement-document` verb return.
+ *
+ * The output is a full ready-to-paste-into-a-PR markdown document that
+ * describes the requirements format, embeds a worked example, and includes
+ * style principles for writing requirements and tests. Discovered label /
+ * key patterns from the calling workspace and (optional) project-owner-
+ * supplied custom guidance are interpolated into the body.
+ *
+ * If the project has a `.requirements/STYLE.md`, callers can pass its
+ * contents via `localStyleGuide` to use that body in place of the bundled
+ * defaults. See {@link readLocalStyleGuide} for the lookup helper.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Conventional location of a project's STYLE.md, relative to the workspace
+ * root. Exported so callers (init, push/pull, tests) can reference one place.
+ */
+export const STYLE_MD_PATH = ".requirements/STYLE.md";
+/**
+ * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
+ * contents on success, `null` if the file is absent. Empty / whitespace-only
+ * files are treated as absent so the bundled defaults still apply.
+ */
+export function readLocalStyleGuide(workspaceRoot) {
+    const fullPath = join(workspaceRoot, STYLE_MD_PATH);
+    if (!existsSync(fullPath)) {
+        return null;
+    }
+    const contents = readFileSync(fullPath, "utf-8");
+    return contents.trim().length > 0 ? contents : null;
+}
+/**
+ * Build the body of the bundled default style guide. This is the content
+ * that lives inside the "# Requirements File Template" preamble — the
+ * format syntax, key/label conventions, style principles, and example
+ * requirements — with discovered patterns and custom guidance interpolated.
+ *
+ * Exposed separately from {@link generateStyleGuide} so callers can:
+ * - scaffold `.requirements/STYLE.md` with the bundled defaults at init time
+ * - swap the body wholesale (via `localStyleGuide`) without losing the
+ *   wrapping preamble + "Next Steps" footer
+ */
+export function generateStyleGuideBody(params) {
+    const { requirements, customStyleGuidance } = params;
+    const labels = new Set();
+    const keyPrefixes = new Set();
+    for (const req of requirements) {
+        if (req.label?.trim()) {
+            labels.add(req.label);
+        }
+        if (req.path.length === 0 && req.id) {
+            const lastDashIndex = req.id.lastIndexOf("-");
+            if (lastDashIndex > 0) {
+                keyPrefixes.add(req.id.substring(0, lastDashIndex));
+            }
+        }
+    }
+    const discoveredLabels = Array.from(labels).sort();
+    const discoveredPrefixes = Array.from(keyPrefixes).sort();
+    let labelGuidance;
+    if (discoveredLabels.length > 0) {
+        const labelList = discoveredLabels
+            .slice(0, 10)
+            .map((l) => `"${l}"`)
+            .join(", ");
+        const more = discoveredLabels.length > 10
+            ? ` (and ${discoveredLabels.length - 10} more)`
+            : "";
+        labelGuidance = `**Existing labels in this codebase:** ${labelList}${more}
+
+**Use these existing labels** to maintain consistency. If you're unsure which labels to use for a new requirement, ask the user.`;
+    }
+    else {
+        labelGuidance = `**No existing requirements found in this codebase.**
+
+**Default to unlabeled requirements** (\`0. → content\`). If the user wants labels, ask them which format they prefer. Do not choose an opinionated framework like Given/When/Then without explicit user consent.`;
+    }
+    let keyGuidance;
+    if (discoveredPrefixes.length > 0) {
+        const prefixList = discoveredPrefixes.map((p) => `"${p}"`).join(", ");
+        keyGuidance = `**Existing requirement key prefixes in this codebase:** ${prefixList}
+
+**Match the existing pattern** when creating new requirement keys. Use the same domain prefixes and sequential numbering style.`;
+    }
+    else {
+        keyGuidance = `**No existing requirements found in this codebase.**
+
+**Use concise domain prefixes** like \`AUTH-1\`, \`LOGIN-1\`, etc. Start numbering at 1 and increment sequentially.`;
+    }
+    let userStyleGuidance = "";
+    if (customStyleGuidance?.trim()) {
+        userStyleGuidance = `
+
+## User-Provided Style Guidelines
+
+The following style guidelines were provided by the project owner. When these conflict with the defaults above, prioritize the user's guidelines.
+
+${customStyleGuidance.trim()}`;
+    }
+    const template = `---
+document:
+  title: "Example Requirements"
+---
+
+# Example Requirements
+
+This template demonstrates the dotrequirements Markdown format and style guidelines.
+
+## Syntax Overview
+
+**File naming:** Use \`*.requirements.md\` pattern (colocated: \`auth.requirements.md\` or centralized: \`.requirements/auth.requirements.md\`)
+
+**Block format:**
+\`\`\`dotrequirements
+KEY: Root requirement content
+  0. → First criterion (unlabeled)
+  1. Label → Second criterion (with label)
+    1.0. → Nested criterion (unlabeled)
+\`\`\`
+
+- First line: \`KEY: content\` (requirement key and description)
+- Criteria: \`position. Label → content\` or \`position. → content\` (unlabeled)
+- Position: \`0\`, \`1\`, \`2\` (top-level) or \`0.0\`, \`1.0\` (nested) - defines hierarchy
+- Delimiter: \`→\` or \`->\` separates optional label from content
+
+## Requirement Keys: Concise and Sequential
+
+${keyGuidance}
+
+**Key format:** \`DOMAIN-FEATURE-N\` where N is sequential (1, 2, 3...)
+
+**Best practices:**
+1. **Concise domains** - Use short, clear prefixes
+   - ✅ \`AUTHZ-1\` (authorization)
+   - ✅ \`AUTH-1\` (authentication)
+   - ❌ \`AUTHORIZATION-1\` (too verbose)
+   - ❌ \`REQ-IDENTITY-ACCESS-AUTHZ-1\` (too nested)
+
+2. **Sequential, 1-indexed numbering** - Start at 1, no padding
+   - ✅ \`LOGIN-1\`, \`LOGIN-2\`, \`LOGIN-3\`
+   - ❌ \`LOGIN-0\` (don't use 0-indexing for requirement IDs)
+   - ❌ \`LOGIN-001\` (no zero-padding)
+
+3. **Unique across project** - Each key must be unique in the entire project
+
+4. **Match existing patterns** - Check existing requirements first and follow their convention
+
+## Labels: Match Your Codebase or Ask the User
+
+${labelGuidance}
+
+## Style Principles for Requirements
+
+**1. Use Concrete Examples**: Replace vague language with specific, testable conditions.
+- ❌ "users can log in" or "works properly"
+- ✅ "When a registered user provides valid credentials, they are authenticated"
+
+**2. Write Natural, Concise Prose**: Avoid terseness and verbosity. Use declarative style (not "should").
+- ❌ "registered user with valid credentials is authenticated" (too terse)
+- ❌ "A registered user, whose account was created on Tuesday and whose life story is as follows..." (too verbose)
+- ✅ "When a registered user provides valid credentials, they are authenticated"
+
+**3. Keep Arrange/Act/Assert in Mind**: Well-written requirements describe preconditions, trigger, and result.
+- ✅ "When [preconditions:] a registered user [trigger:] provides valid credentials, [result:] they are authenticated"
+
+**4. Be Framework Neutral**: Don't prescribe Given/When/Then vs AC vs other formats - focus on content quality.
+
+**5. Use Named Personas**: Establish personas in parent requirements, reuse in children.
+- ✅ Parent: "A registered user, Jamie, can log in normally" → Child: "When Jamie provides valid credentials, they are authenticated"
+
+**6. Use User-Centric Language**: Describe user experience, not technical internals.
+- ❌ "they are redirected to app.dotrequirements.io/redirect/dashboard"
+- ✅ "they are automatically brought to the dashboard"
+
+**7. Single Action Per Requirement**: Don't chain multiple actions with "and then".
+- ❌ "When Robin provides credentials, requests an OTP, then provides the OTP..."
+- ✅ Break into separate requirements for each action
+
+**8. Each Requirement Should Be Independent**: Requirements within a block should be independently testable. If they share preconditions or form a sequence, either nest them or restate context.
+- ❌ "0. → When Jordan submits signup, an account is created" / "1. → Welcome email is sent" / "2. → Dashboard appears"
+- ✅ Option A: Restate context - "1. → When Jordan submits signup, a welcome email is sent"
+- ✅ Option B: Use nesting - "0. When → Jordan submits signup" / "  0.0. Then → an account is created"
+- Test: Can you understand what's being tested by reading just one requirement, or do you need to read its siblings?
+
+**9. Focus on Behavior, Not Design**: Describe what happens, not UI specifics.
+- ❌ "enters valid credentials into two single-line input fields and presses a green button"
+- ✅ "provides valid credentials"
+
+**10. Focus on Outcomes, Not Implementation**: User perspective, even for technical requirements.
+- ❌ "When the app requests that Twilio send Casey an OTP from /email/POST endpoint..."
+- ✅ "When Casey requests an email OTP..."
+- Note: Even technical requirements can be user-centric: "95 percent of users experience under 1 second of delay"
+
+**11. Decompose Large Requirements**: If it can't be validated with a single test, break it down.
+${userStyleGuidance}
+
+## Example Requirements
+
+**Unlabeled (recommended default):**
+\`\`\`dotrequirements
+AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
+  0. → When Jamie provides their registered email and correct password, they are authenticated and brought to their dashboard
+  1. → When Jamie provides an incorrect password, they see an error message and remain on the login page
+  2. → When Jamie's account has been deactivated, they see a message explaining their account status
+\`\`\`
+
+**With labels (example only - DO NOT use opinionated formats like Given/When/Then without asking the user first):**
+\`\`\`dotrequirements
+PAYMENT-REFUND-1: A customer, Alex, receives a refund after returning an item
+  0. Given → Alex purchased a laptop from the store 10 days ago
+  1. Given → Alex initiates a return through their order history
+  2. When → Alex's returned laptop is received and inspected at the warehouse
+  3. Then → Alex receives a refund to their original payment method within 5 business days
+  4. Then → Alex receives an email confirmation with the refund amount and expected timeline
+\`\`\`
+
+## Referencing Requirements in Tests
+
+**Use \`requirement()\` as the test description** - it returns a string:
+
+\`\`\`typescript
+import { describe, it, expect } from 'vitest';
+import { requirement } from '@popoverai/dotrequirements/test';
+
+describe(requirement('AUTH-LOGIN-1'), () => {
+  describe(requirement('AUTH-LOGIN-1.given'), () => {
+    // Arrange: Create Jamie's account
+  });
+
+  describe(requirement('AUTH-LOGIN-1.when'), () => {
+    // Act: Submit login with valid credentials
+
+    it(requirement('AUTH-LOGIN-1.then'), () => {
+      // Assert: Jamie is authenticated
+    });
+  });
+});
+\`\`\`
+
+**Test Style Principles:**
+
+**1. Use requirement() AS the description**: Don't put requirement() inside test body or in comments.
+- ✅ \`test(requirement('AUTH-LOGIN-1'), () => { /* test code */ })\`
+- ✅ \`it(requirement('LOGIN-1.then'), () => { /* assert */ })\`
+- ❌ \`test("user can log in", () => { requirement('AUTH-LOGIN-1'); /* test code */ })\`
+- ❌ \`// LOGIN-1: User can log in\` (comment instead of using requirement() as description)
+
+**2. Comments describe the TEST, not the requirement**: Don't copy requirement text verbatim.
+- ✅ \`describe(requirement('REQ-1.0'), () => { // registered user, valid credentials\`
+- ❌ \`describe(requirement('REQ-1.0'), () => { // 0. When a registered user provides valid credentials, they are authenticated\` (verbatim copy is a red flag)
+- Note: Comments should reflect what the test actually does, not just repeat what the requirement says
+
+**3. Structure tests to match requirements**: Nest describe/it blocks for structured requirements.
+- ✅ For structured requirements: \`describe(requirement('LOGIN-1.given'))\` nested with \`describe(requirement('LOGIN-1.when'))\` and \`it(requirement('LOGIN-1.then'))\`
+- ✅ For simple requirements: \`test(requirement('AUTH-LOGIN-1'), () => { /* arrange, act, assert all in one */ })\`
+
+**Path formats:**
+- \`requirement('AUTH-LOGIN-1')\` - root requirement
+- \`requirement('AUTH-LOGIN-1.0')\` - by numeric position
+- \`requirement('AUTH-LOGIN-1.given')\` - by label (case-insensitive)
+- \`requirement('AUTH-LOGIN-1.given#1')\` - disambiguate duplicate labels`;
+    return template;
+}
+/**
+ * Build a complete style-guide document for the calling workspace.
+ * Returns a single markdown string suitable for printing to stdout or
+ * wrapping in an MCP text response.
+ *
+ * When `localStyleGuide` is provided and non-empty, that content replaces
+ * the bundled default body. The preamble and "Next Steps" footer are
+ * always applied.
+ */
+export function generateStyleGuide(params) {
+    const { filePath = ".requirements/example.requirements.md", localStyleGuide, } = params;
+    const body = localStyleGuide?.trim()
+        ? localStyleGuide
+        : generateStyleGuideBody(params);
+    return `# Requirements File Template
+
+Here's a comprehensive template for \`${filePath}\` with format and style guidance:
+
+\`\`\`markdown
+${body}
+\`\`\`
+
+## Next Steps
+
+1. **Create file**: Save this template as \`${filePath}\` and edit it for your feature
+2. **Refine style** (optional): Run \`style-check\` (or call the \`style_check\` MCP tool) for AI feedback
+3. **Validate syntax**: Run \`validate\` (or call the \`validate\` MCP tool) to verify format
+4. **Push to cloud**: Run \`dotrequirements push\` (or call the \`push_requirements\` MCP tool) to sync
+
+**Note**: Requirements files can be colocated with code (\`src/auth.requirements.md\`) or centralized in \`.requirements/\` directory.`;
+}
+//# sourceMappingURL=style-guide.js.map

package/dist/requirements/testCodeExtractor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Extract test code context using @babel/parser AST traversal.
+ *
+ * Finds requirement() call references and extracts the enclosing
+ * meaningful code block (function, describe, test, etc.)
+ */
+export interface TestCodeReference {
+    file: string;
+    startLine: number;
+    endLine: number;
+    code: string;
+    requirementId: string;
+}
+/**
+ * Find all test code blocks that reference a specific requirement
+ */
+export declare function findTestCodeForRequirement(filePath: string, requirementId: string): TestCodeReference[];
+/**
+ * Find all files that reference a requirement
+ */
+export declare function findFilesWithRequirement(files: string[], requirementId: string): string[];
+//# sourceMappingURL=testCodeExtractor.d.ts.map