GO — Healthy across the board

• Last commit 3mo ago
• 29+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

remark is a markdown processor built on the unified.js ecosystem that parses markdown into Abstract Syntax Trees (ASTs), applies plugin transformations, and serializes back to markdown or other formats. It's a 100% CommonMark-compliant parser with 150+ available plugins, enabling programmatic inspection and modification of markdown documents at the structural level. Monorepo with 4 packages under /packages: (1) remark-parse handles markdown→AST parsing via micromark, (2) remark-stringify handles AST→markdown serialization, (3) remark combines both with unified for the main API, (4) remark-cli wraps remark for command-line usage. Each package is independently versioned and published to npm. The lib/ subdirectories contain implementation details, index.d.ts provides TypeScript definitions, and root test.js runs integration tests across all packages.

Developers building markdown-based tooling: documentation generators, linters (via remark-lint plugins), static site generators, content management systems, and CLI tools that need to transform or validate markdown. Also used by maintainers of unified ecosystem plugins who extend remark's capabilities.

Production-ready and actively maintained. The project is well-established within the unified collective (used by Prettier, Next.js docs, and thousands of npm packages), has 100% type coverage (enforced in tsconfig), comprehensive test suite (test.js with c8 code coverage at 100%), and automated CI/CD via GitHub Actions. Regular commits and an organized monorepo structure indicate active development.

Low risk for core functionality. The remark package itself has minimal direct dependencies (mostly unified ecosystem packages like unified@^11.0.0 and @types/mdast@^4.0.0), and the monorepo structure (4 workspaces) keeps concerns isolated. Primary risk is community plugin quality variance — users must vet third-party plugins. Single ecosystem maintainer (@unifiedjs collective) means breaking changes affect the whole ecosystem, but semver is strictly enforced.

Cannot determine from provided file snapshot alone. Check /packages/remark/package.json for current version, review GitHub Actions workflows in .github/workflows/ (main.yml likely runs tests on push), and examine recent changelog.md entries for recent feature work.

git clone https://github.com/remarkjs/remark
cd remark
npm install
npm run build
npm test

Daily commands: Development: npm run build (TypeScript compilation with tsc --build), npm run test-api (node test.js runs integration tests), npm run format (remark CLI + prettier + xo linting), npm test (runs all: build, format, test-coverage). No dev server—this is a library. For CLI usage: ./packages/remark-cli/cli.js --help or npm exec remark -- --help after install.

• packages/remark/index.js: Main entry point; exports the unified() processor with attached parse and stringify plugins
• packages/remark-parse/lib/index.js: Core parser logic; implements markdown tokenization and AST generation using micromark
• packages/remark-stringify/lib/index.js: Core serializer; converts AST nodes back into markdown strings with configurable formatting
• packages/remark-cli/cli.js: Command-line interface; processes files/stdin via remark and outputs results or linting reports
• test.js: Integration test suite; validates parse→AST→stringify round-trip and plugin interactions across all packages
• package.json: Workspace configuration; defines build, test, and format scripts; declares 4 monorepo packages and shared devDependencies

Adding parse logic: edit /packages/remark-parse/lib/index.js (attach tokenizers to parser). Adding stringify logic: edit /packages/remark-stringify/lib/index.js (handle specific AST node types). New public API: modify /packages/remark/index.js to export from parse/stringify. Adding tests: extend test.js with import statements and test() calls. Type definitions: update corresponding index.d.ts files in each package. CLI features: modify /packages/remark-cli/cli.js.

1. Monorepo linkage: packages/ are symlinked via workspaces; you must run npm install at root, not in individual packages. 2. Type coverage enforcement: tsconfig.json has 100% coverage requirement; missing @ts-ignore or type annotations will fail the build. 3. AST mutations are in-place: plugins receive mutable AST objects; the unified processor does not auto-clone, so side effects are real. 4. Markdown dialect differences: remark-parse is CommonMark-compliant by default; GFM or MDX require explicit plugins (mdast-util-gfm, etc.), not bundled. 5. CLI requires file paths or stdin redirection: remark-cli/cli.js does not glob by default; you must pass explicit file args or use shell globbing.

• Abstract Syntax Tree (AST) — Remark's core abstraction; you work with tree structures (mdast), not raw strings, enabling reliable transformations and tool composition
• Plugin architecture / Pipeline pattern — Remark's entire design revolves around composable plugins via unified's use() API; understanding plugin registration, execution order, and data flow is essential
• CommonMark specification — Remark claims 100% compliance; knowing CommonMark's rules for lists, links, emphasis, code blocks distinguishes valid from invalid markdown and explains parser behavior
• Tokenization / Lexing — Remark delegates tokenization to micromark (not included in visible files but integrated); understanding how raw markdown bytes become tokens informs parser plugin development
• Visitor pattern (AST traversal) — Most remark plugins walk the AST tree via unist-util-visit; recognizing this pattern helps you iterate, filter, and transform nodes efficiently
• VFile (Virtual File abstraction) — Unified/remark passes markdown through VFile objects that carry metadata, messages, and position info; crucial for error reporting and preserving source maps
• Monorepo management with npm workspaces — Remark's repo uses npm workspaces (not Lerna) to manage 4 interdependent packages; symlinks and hoisting mean local changes propagate without re-publishing

• unifiedjs/unified — Core plugin architecture and processor API that remark builds upon; required understanding for extending remark with custom plugins
• syntax-tree/mdast — AST specification for markdown; defines node types (Heading, Paragraph, etc.) that remark-parse generates and remark-stringify consumes
• remarkjs/remark-lint — Official linting plugin suite for remark; shows how to build plugins that inspect AST nodes and report violations without modifying content
• syntax-tree/mdast-util-gfm — GitHub Flavored Markdown support plugin; integrates with remark-parse/stringify to handle tables, strikethrough, task lists not in CommonMark
• rehypejs/rehype — Sister project for HTML processing; common companion to remark via remark-rehype bridge for markdown→HTML transformation pipelines

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for remark-cli with common plugin combinations

The remark-cli package (packages/remark-cli/) lacks comprehensive integration tests demonstrating real-world usage scenarios. Currently test.js appears to be a root-level test file, but there are no specific CLI tests for common workflows like: parsing with GFM extensions, formatting with preset plugins, and error handling. This would improve confidence in CLI reliability and serve as documentation for users.

• [ ] Create packages/remark-cli/test.js with test cases for basic markdown parsing via CLI
• [ ] Add tests for --preset flag with remark-preset-wooorm
• [ ] Add tests for GFM plugin integration (micromark-extension-gfm + mdast-util-gfm)
• [ ] Add tests for --frail flag error handling behavior
• [ ] Ensure c8 coverage reports include CLI tests in npm run test-coverage

Add TypeScript strict mode compliance tests in CI workflow

The repo has "strict": true in typeCoverage config and TypeScript 5.0, but .github/workflows/main.yml doesn't explicitly verify TypeScript strict mode compilation. The existing build script runs tsc, but there's no dedicated CI check for strict type safety that would catch regressions early. This ensures type safety across all packages.

• [ ] Update .github/workflows/main.yml to add a step: npm run build with explicit error on tsc warnings
• [ ] Verify tsconfig.json in root and all packages (remark-parse, remark-stringify, remark, remark-cli) have consistent strict settings
• [ ] Document strict mode requirements in packages/*/readme.md files

Add documentation for extending remark with custom AST transformations in doc/getting-started.md

The doc/getting-started.md file exists but likely lacks concrete examples of plugin development patterns that are specific to the unified/mdast ecosystem. New contributors need guidance on: visiting AST nodes, modifying the syntax tree, and maintaining AST node types. This directly addresses the 'plugins' feature highlight mentioned in the README.

• [ ] Add section to doc/getting-started.md: 'Creating Your First Plugin' with a working example using unist-util-visit or similar
• [ ] Include an example showing how to transform a markdown AST node (e.g., converting emphasis to bold)
• [ ] Link to @types/mdast (already in devDependencies) for AST node type reference
• [ ] Show how to properly type plugin exports using TypeScript as demonstrated in existing packages

• Add missing test cases for edge-case markdown syntax in test.js (e.g., deeply nested lists, mixed quote styles, Unicode in headings) to reach coverage gaps visible in packages/remark-parse/lib/index.js
• Expand CLI help text in packages/remark-cli/cli.js with concrete usage examples (e.g., remark file.md --fix, remark --stdin-other markdown) matching the README but currently missing from --help output
• Add TypeScript generics documentation to packages/remark/index.d.ts explaining how to type plugin transformations and VFile data (currently minimal JSDoc) to reduce plugin author confusion

The remark codebase demonstrates a generally secure posture as a markdown processing library. The monorepo structure is clean with no hardcoded secrets, exposed credentials, or obvious injection vulnerabilities visible. However, there are opportunities for improvement: 1) Stricter TypeScript compilation flags should be enforced, 2) CLI input validation should be documented and robust, 3) XSS risks should be clearly communicated to users when markdown is rendered to HTML, and 4) Dependency management should leverage lock files consistently. The project follows security best practices with MIT licensing, active maintenance, and community governance through OpenCollective. No critical vulnerabilities were identified in the provided files.

• Low · Permissive TypeScript Configuration — tsconfig.json, packages/*/tsconfig.json. The root tsconfig.json and package-level configurations lack explicit security-focused compiler options. Missing strict null checks, noImplicitAny, and noImplicitThis could allow type-related vulnerabilities to slip through. Fix: Enable strict mode in tsconfig.json: set 'strict': true, 'noImplicitAny': true, 'strictNullChecks': true, 'noImplicitThis': true
• Low · Missing Security Headers in CLI Configuration — packages/remark-cli/cli.js. The remark-cli package executes markdown processing which could be exposed to user input. No explicit input validation or sanitization patterns are evident in the file structure. Fix: Implement input validation for CLI arguments and file inputs. Consider adding limits on file size and recursion depth for markdown parsing.
• Low · Dependency Pinning Not Enforced — package.json. While devDependencies are specified with caret (^) version ranges, there's no lock file visible in the provided structure. This could lead to unexpected updates of transitive dependencies. Fix: Ensure package-lock.json or yarn.lock is committed and CI/CD uses '--ci' or '--frozen-lockfile' flags. Consider using exact pinning for critical security dependencies.
• Low · XSS Risk in Markdown Processing — packages/remark-stringify/lib/index.js, packages/remark-parse/lib/index.js. The remark-stringify package converts ASTs back to markdown. If user-controlled content is processed without proper escaping, HTML injection could occur when the markdown is rendered to HTML downstream. Fix: Document security implications clearly. Ensure output is sanitized if rendered as HTML. Users should apply appropriate HTML sanitization layers (e.g., sanitize-html, DOMPurify) when converting markdown output to HTML.
• Low · Missing Subresource Integrity for External Dependencies — package.json. No SRI (Subresource Integrity) hashes are visible in the package configuration for client-side usage scenarios. Fix: If this package is used in client-side contexts, document the need for SRI hashes and provide integration guidance.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/remarkjs/remark shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live remarkjs/remark repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/remarkjs/remark.

What it runs against: a local clone of remarkjs/remark — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in remarkjs/remark | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 105 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of remarkjs/remark. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/remarkjs/remark.git
#   cd remark
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of remarkjs/remark and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "remarkjs/remark(\\.git)?\\b" \\
  && ok "origin remote is remarkjs/remark" \\
  || miss "origin remote is not remarkjs/remark (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 105 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~75d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/remarkjs/remark"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.