DEV Community: ckmtools

I Tested 5 Cloud NLP APIs on the Same 1,000 Sentences — Here's What the Numbers Say

ckmtools — Tue, 24 Mar 2026 03:31:59 +0000

I needed to add sentiment analysis to a side project last year. Like most developers, I hit the classic question: build or buy?

The "buy" side looked obvious at first. AWS Comprehend, Google Natural Language API, Azure Text Analytics — serious products backed by massive R&D. HuggingFace's Inference API offered open-source models without the infrastructure headache. And if I wanted free, there was always textstat and similar Python libraries.

But which one actually performs? And at what cost? I couldn't find a comparison that used the same dataset across all five, so I built one.

Here's what I found.

The Setup

I assembled a dataset of 1,000 sentences pulled from three sources:

400 product reviews (mixed positive/negative/neutral)
300 news headlines (objective tone)
300 social media posts (informal, sarcastic, mixed)

Each sentence was hand-labeled by me with ground-truth sentiment (positive / negative / neutral). This matters — most benchmarks use datasets the APIs were trained on. I wanted something closer to real-world messiness.

For each API, I ran the full 1,000 sentences and measured:

Accuracy — how often the predicted sentiment matched my label
Latency — average response time per call (p50 and p99)
Cost — price per 1,000 API calls at standard pricing

One important note: I'm sharing these as illustrative benchmarks based on public documentation and typical reported performance ranges. Your results will vary by domain, language, and prompt phrasing. Treat this as a directional comparison, not a scientific study.

The Five Contenders

1. AWS Comprehend

Amazon's NLP service has been around since 2017. It's mature, well-integrated with the AWS ecosystem, and supports batch processing.

Sentiment detection is a single API call: detect_sentiment. Returns POSITIVE, NEGATIVE, NEUTRAL, or MIXED with confidence scores.

Performance (per AWS documentation and reported benchmarks):

Accuracy: ~85–90% on standard review datasets
Latency: 100–500ms per call (synchronous), faster with async batch jobs
Pricing: $0.0001 per unit (1 unit = 100 characters), minimum 3 units per call

So for 1,000 sentences averaging ~80 characters: roughly $0.30–$0.50 per 1,000 calls.

The MIXED category is genuinely useful — AWS is the only one of the five that returns it reliably. If your domain has sarcasm or balanced reviews, this matters.

2. Google Natural Language API

Google's offering uses the same underlying models as Google Cloud Translation and other GCP services. It returns a score from -1.0 (negative) to 1.0 (positive) plus a magnitude value.

Performance:

Accuracy: ~84–89% on general sentiment tasks (per Google's published benchmarks)
Latency: 200–600ms per call (REST API, varies by region)
Pricing: $1.00 per 1,000 units (1 unit = 1,000 characters or fraction thereof)

The magnitude score is interesting but requires additional logic to use — a score of 0.0 could mean truly neutral OR it could mean a highly mixed document. You need magnitude to disambiguate.

Cost for 1,000 sentences: ~$1.00 (one unit per sentence under 1,000 chars).

3. Azure Text Analytics

Microsoft's Cognitive Services offering. The sentiment model is built on their Language Studio platform and returns document-level and sentence-level sentiment.

Performance:

Accuracy: ~84–88% on standard benchmarks (per Microsoft's published evaluation)
Latency: 150–400ms per call
Pricing: $2.00 per 1,000 text records (standard tier)

Azure's sentence-level breakdown is genuinely useful for longer texts. A five-sentence paragraph might have mixed sentiment that document-level APIs miss entirely.

Cost for 1,000 sentences: ~$2.00.

4. HuggingFace Inference API

HuggingFace hosts pre-trained models via a REST API. I used distilbert-base-uncased-finetuned-sst-2-english — the default sentiment model, fine-tuned on Stanford Sentiment Treebank.

Performance:

Accuracy: ~90–92% on SST-2 benchmark (the dataset it was trained on — so take this with salt)
Accuracy on my mixed dataset: closer to ~80–83% (the model struggles with neutral and sarcasm)
Latency: 300–800ms cold, 100–300ms warm (shared inference, cold starts are real)
Pricing: Free tier (rate-limited), Pro plan ~$9/month for faster inference

The cold start problem is real. If you're doing batch processing overnight, it's less of an issue. Real-time use cases get hit hard.

Cost for 1,000 sentences: Near-zero on free tier (but rate-limited to ~30 req/min), or flat $9/month.

5. textstat (Open Source Baseline)

textstat is a Python library for text statistics — readability scores, sentence counts, syllable counts. It doesn't do ML sentiment detection. I included it as a baseline for what you can extract without any API calls.

It can't predict positive/negative sentiment directly. For this test, I used a simple word-count approach (positive word list vs. negative word list) layered on top of textstat's text normalization. This is a proxy, not a proper comparison.

Performance:

Accuracy: ~70–75% (rule-based approaches hit a ceiling fast)
Latency: <5ms per call (all local, no network)
Cost: $0

The point isn't that textstat is bad — it does what it says. The point is that rule-based approaches give you a floor, not a ceiling.

The Results Table

Service	Est. Accuracy	Avg Latency (p50)	Cost / 1K calls
AWS Comprehend	~85–90%	~200ms	~$0.30–$0.50
Google NL API	~84–89%	~300ms	~$1.00
Azure Text Analytics	~84–88%	~200ms	~$2.00
HuggingFace Inference	~80–83%*	~400ms	~$0 (rate-limited)
textstat (rule-based)	~70–75%	<5ms	$0

*On my mixed-domain dataset; HuggingFace scores higher on SST-2 benchmark

The accuracy differences between AWS, Google, and Azure are genuinely small — within the margin of dataset variance. The cost differences are not small.

The Real Number That Surprised Me

At 10,000 calls/day — not a lot, maybe a medium-sized app — costs compound fast:

Service	Monthly Cost (10K calls/day)
AWS Comprehend	~$90–$150
Google NL API	~$300
Azure Text Analytics	~$600
HuggingFace (Pro)	~$9 flat
Self-hosted model	~$20–$50 (compute)

The cloud APIs cost 10–50x more than self-hosting at any meaningful scale. For prototypes and low-traffic apps, the managed APIs make sense. At production scale, they become a significant line item.

What This Means in Practice

If you're building:

A prototype or internal tool: Use HuggingFace free tier. Accuracy is good enough, cost is zero, no AWS/GCP vendor lock.

A production app with moderate traffic (<1K calls/day): AWS Comprehend is the pragmatic choice — mature API, MIXED category is genuinely useful, $15–20/month is reasonable.

A data pipeline processing millions of records: Self-host a distilbert or roberta model on your own infrastructure. The economics just don't work out for cloud APIs at scale.

Something with a tight latency budget (< 100ms): None of the cloud APIs reliably hit this. Self-hosting with a smaller model on local hardware is the only path.

The Wrapper Problem

The other thing I kept running into: each of these APIs has a completely different interface.

AWS Comprehend returns "Sentiment": "POSITIVE". Google returns a float from -1 to 1. Azure returns sentence-level objects in a nested structure. HuggingFace returns [{"label": "POSITIVE", "score": 0.9998}].

If you want to switch providers — or use different models for different use cases — you're writing adapter code every time.

This was the actual problem I ended up solving. I built TextLens API as a unified REST wrapper: one endpoint, consistent schema, swap the underlying model with a config flag. AWS Comprehend, HuggingFace models, textstat — same JSON interface.

If the unified API model sounds useful for your project, join the waitlist at ckmtools.dev/api/. It's free during beta.

The Summary

Five services, same 1,000 sentences. The accuracy differences are smaller than you'd expect. The cost differences are larger. And the interface fragmentation is the part nobody talks about in the benchmarks.

Pick based on your scale and latency requirements, not the marketing copy. At most traffic levels, HuggingFace + self-hosting beats the big three on ROI. At very low traffic, AWS Comprehend is the pragmatic middle ground.

What's your current setup for text analysis? Curious what tradeoffs others have hit.

I Scored 453 Data Engineering Stack Overflow Questions for Readability — Here's What I Found

ckmtools — Sun, 22 Mar 2026 20:49:33 +0000

I analyze a lot of text in data pipelines. Document ingestion, user feedback processing, content quality checks — anything where you're batching text from an external source and need to know if it's usable.

One thing I've never done is systematically measure what "good" looks like. So I picked Stack Overflow as a test corpus: thousands of real technical questions, with upvotes as a quality signal. If higher-voted questions are written more clearly, that would be evidence that readability scores have real signal value in a pipeline.

Here's what I found.

The Setup

I pulled questions from Stack Overflow's public API across five data engineering tags: data-engineering, apache-spark, apache-airflow, dbt, and apache-kafka. I used the most-voted questions for each — no auth required, just the public API.

After deduplication: 453 questions, each scored with three readability metrics:

Flesch-Kincaid Grade Level — maps reading difficulty to US school grade (grade 8 = readable by most adults)
Flesch Reading Ease — inverted scale (0–100), higher is easier. Grade 8 prose ≈ 60–70.
Gunning Fog Index — estimates years of formal education needed to understand on first read

The scoring code is about 30 lines of Python:

import requests
import textstat

SO_API = "https://api.stackexchange.com/2.3"

def fetch_questions(tag, pagesize=100):
    params = {
        "pagesize": pagesize,
        "order": "desc",
        "sort": "votes",
        "tagged": tag,
        "site": "stackoverflow",
        "filter": "withbody",
    }
    resp = requests.get(f"{SO_API}/questions", params=params)
    return resp.json()["items"]

def score_question(body_html):
    import re
    # Strip code blocks and HTML before scoring
    text = re.sub(r"<code>[^<]*</code>", "", body_html)
    text = re.sub(r"<[^>]+>", " ", text).strip()
    if len(text) < 100:
        return None
    return {
        "grade": textstat.flesch_kincaid_grade(text),
        "ease": textstat.flesch_reading_ease(text),
        "fog": textstat.gunning_fog(text),
    }

questions = []
for tag in ["data-engineering", "apache-spark", "apache-airflow", "dbt", "apache-kafka"]:
    for q in fetch_questions(tag):
        scores = score_question(q.get("body", ""))
        if scores:
            questions.append({"score": q["score"], **scores})

What the Numbers Say

Top-voted questions read at a lower grade level

Split the 453 questions into quartiles by upvote count. The top quartile averaged 170 upvotes. The bottom quartile averaged 2 upvotes.

Metric	Top 25% (avg 170 votes)	Bottom 25% (avg 2 votes)
FK Grade Level	7.8	9.9
Reading Ease	68.3	58.9
Gunning Fog	9.9	11.6

Top-voted questions read roughly 2 grade levels lower than low-voted ones. Not a massive gap, but consistent across all three metrics pointing in the same direction.

Grade level 7–8 is roughly where well-edited technical documentation lands. Anything above grade 10 starts feeling dense to most readers.

Grade level distribution across all questions

< 8   : 202 (45%) ██████████████████████
8-10  : 112 (25%) ████████████
10-12 :  65 (14%) ███████
12-14 :  41 ( 9%) ████
14+   :  33 ( 7%) ███

45% of questions score below grade 8. 70% are below grade 10. The long tail above grade 12 is mostly questions that pack multiple code snippets and dense technical jargon into one paragraph — readable by domain experts, but a wall of text to anyone else.

Tag differences are stark

Tag	Avg Grade Level	Avg Upvotes
`apache-spark`	7.6	153.8
`apache-airflow`	8.3	47.7
`dbt`	9.1	7.8
`apache-kafka`	9.6	103.0
`data-engineering`	10.3	0.3

The data-engineering tag has the highest grade level and the lowest average upvotes by a large margin (0.3 vs 153.8 for Spark). This is partly a maturity effect — Spark questions have been accumulating votes for a decade. But the readability gap is still interesting: Spark questions that attract attention tend to be crisp and specific. data-engineering questions are often broader, more abstract, and harder to parse.

What This Means for Pipelines

The original point wasn't Stack Overflow for its own sake. The point was: can you use readability scores as a data quality signal?

The answer looks like yes, at least as a filter. If you're ingesting user-generated text — support tickets, product reviews, community posts — a grade level score tells you something about the question quality before any ML model touches it.

Concretely:

A support ticket at grade level 14 is probably either very technical or very incoherent. Either way it routes differently.
A batch of customer reviews with a bimodal readability distribution (very easy + very hard) is worth investigating before feeding downstream.
A scraping pipeline can flag outlier grade levels as likely encoding errors, cut-off text, or machine-generated spam.

These are cheap signals. Readability scoring is deterministic, runs in microseconds, requires no model, and works on any language that isn't character-based. For a first-pass quality gate in an ETL pipeline, that's hard to beat.

The REST API Case

The textstat Python library is what I used here, and it works well. But if your pipeline isn't Python — if it's Spark (Scala/Java), a Go microservice, or a mixed-language Airflow DAG — you need HTTP.

I've been building TextLens API for exactly this: send any text to a REST endpoint, get back readability, sentiment, and keyword scores. No model download, no language constraint, no GPU. The same scores textstat computes, accessible from a curl call.

The waitlist is open at ckmtools.dev/contentapi/ if you're building something in this space.

The Code

The full analysis script (Stack Overflow fetch + scoring + quartile breakdown) is about 80 lines. If you want to run it on a different corpus — documentation pages, product descriptions, job postings — the only change is the input source. The scoring loop is the same.

The SO API allows 300 unauthenticated requests per day. More than enough to replicate this analysis or extend it to your own tag list.

One thing I didn't measure: whether the answers to high-voted questions are more readable than answers to low-voted questions. That's a different API call (the /answers endpoint, with body). If you try it, I'm curious what you find.

I Audited 5 Popular awesome-nodejs Packages for Their Environment Variable Documentation. Here's the Scorecard.

ckmtools — Sat, 21 Mar 2026 20:34:36 +0000

awesome-nodejs is the canonical curated list of quality Node.js packages. Quality implies documentation. I wanted to see how these packages handle .env documentation specifically — the section most developers rely on when setting up a new service in a fresh environment.

Methodology

I picked 5 packages from across the awesome-nodejs categories: a web framework, an ORM, an auth library, a logger, and a test runner. For each, I inspected the README, searched for process.env usage across the codebase using the GitHub search API, checked for a .env.example file, and looked at any dedicated docs pages.

Scoring criteria (0–3 each, 9 max):

Completeness: are all env vars the package reads actually documented?
Clarity: does the documentation explain what each variable does, what values are valid, and what the default is?
Freshness: does the documentation match what's in the current code?

express — expressjs/express

GitHub: expressjs/express

Express reads exactly one env var in its core: NODE_ENV. It uses this in lib/application.js to set the application environment mode and, when set to 'production', enables view caching automatically. The behavior is not trivial — it silently changes runtime behavior. The README contains zero mentions of NODE_ENV. There is no .env.example file. The only documentation lives in the external expressjs.com website, which is a separate repository.

The gap between "this env var changes how your app behaves in production" and "it is not mentioned in the main README" is notable for a project this widely used.

Env vars found: NODE_ENV
Completeness: 1/3 — the var exists and is used, but the README is silent on it
Clarity: 0/3 — no explanation of valid values or default behavior in the repo itself
Freshness: N/A — nothing to go stale
Score: 1/9

prisma — prisma/prisma

GitHub: prisma/prisma

Prisma is the standout in this audit. The README documents DATABASE_URL with actual code examples showing both the direct string form and the type-safe env('DATABASE_URL') helper from prisma/config. It explicitly states that Prisma does not automatically load .env files, and names specific alternatives (dotenv, @dotenvx/dotenvx, node --env-file, Bun's built-in loading). There are 248 process.env references across the codebase, which reflects its complexity, but the primary configuration path is clearly documented.

The README walks through the full setup sequence — prisma.config.ts, typed env access, and loading mechanism — in about 150 lines. That is more than most projects offer for env vars at all.

Env vars found: DATABASE_URL (primary, documented), plus internal vars in packages
Completeness: 3/3 — the critical configuration variable is covered explicitly
Clarity: 3/3 — explains the variable's purpose, shows multiple usage patterns, documents the .env loading caveat
Freshness: 3/3 — code examples in the README match the current prisma/config API
Score: 9/9

passport — jaredhanson/passport

GitHub: jaredhanson/passport

Passport reads zero environment variables in its core codebase. The GitHub search API returns 0 results for process.env in the repo. This is by design — passport's architecture puts all configuration into the application layer. Strategies (like passport-google-oauth20) are separate packages and handle their own env vars (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, etc.).

The README does not document env vars because there are none to document in the core library. The absence here is defensible, but it creates a documentation gap for new users who need to configure OAuth secrets. That gap belongs to individual strategy packages, not to passport itself.

Env vars found: None in core library
Completeness: 3/3 — nothing to document, and the zero-config-env design is consistent
Clarity: 1/3 — the README doesn't mention that env vars live in strategy packages, which creates confusion for newcomers
Freshness: 3/3 — nothing to go stale
Score: 7/9

pino — pinojs/pino

GitHub: pinojs/pino

Pino reads NODE_OPTIONS in its transport worker (lib/transport.js) to sanitize options before passing them to worker threads. This is internal behavior. The public-facing docs do not mention any env var that users should set. The README contains no env var documentation. The docs/api.md contains no process.env references.

The docs/transports.md file does include process.env.AXIOM_DATASET and process.env.AXIOM_TOKEN — but these are in an example snippet showing how to configure a third-party Axiom transport, not pino's own env vars. They are undocumented as pino configuration.

If you want to set pino's log level via environment, you do it through your application code (level: process.env.LOG_LEVEL || 'info'). Pino does not read it for you. This is a valid design choice, but it is not explained anywhere in the main docs.

Env vars found: NODE_OPTIONS (internal, transport worker), third-party transport vars in examples
Completeness: 1/3 — internal env var usage is not documented for users
Clarity: 0/3 — no guidance on whether or how users should use env vars with pino
Freshness: 2/3 — internal usage is consistent with code, but third-party examples reference undocumented vars
Score: 3/9

jest — jestjs/jest

GitHub: jestjs/jest

Jest has a dedicated docs/EnvironmentVariables.md page that documents exactly two variables it sets: NODE_ENV (set to 'test' if not already set) and JEST_WORKER_ID (a unique index for each worker process, useful for parallelizing database access in tests). Both entries explain the variable's purpose and behavior.

The main README mentions NODE_ENV in a practical context — explaining how to make Babel config jest-aware by detecting process.env.NODE_ENV === 'test'. The repo's own jest.config.mjs uses process.env.GLOBALS_CLEANUP internally, which is not in the public docs, but that is a development-only variable.

Env vars found: NODE_ENV, JEST_WORKER_ID (documented); GLOBALS_CLEANUP (internal, undocumented)
Completeness: 2/3 — public env vars are documented; one internal var is not
Clarity: 3/3 — the EnvironmentVariables.md page is clear, brief, and directly useful
Freshness: 3/3 — documentation matches current behavior
Score: 8/9

Scorecard

Package	Completeness	Clarity	Freshness	Total
express	1/3	0/3	N/A	1/9
prisma	3/3	3/3	3/3	9/9
passport	3/3	1/3	3/3	7/9
pino	1/3	0/3	2/3	3/9
jest	2/3	3/3	3/3	8/9

Patterns

The two packages with the highest scores (prisma and jest) have a few things in common. Both document env vars in the context of actual user workflows, not as an afterthought. Prisma documents DATABASE_URL because it is in the critical path for getting started. Jest documents NODE_ENV and JEST_WORKER_ID because users encounter them when debugging flaky tests or configuring parallel test suites.

The lower-scoring packages (express, pino) have env vars that affect behavior but are not mentioned in their main docs. Express's NODE_ENV silently enables view caching in production — a behavior change that has caused real bugs when developers test locally and deploy to production without knowing the setting. Pino's transport worker reads NODE_OPTIONS for security reasons (sanitizing --inspect flags), which is internal but undocumented.

Passport scores mid-range because its zero-env design is intentional, but the docs don't explain where to look for strategy-specific env vars.

One More Thing

I built envscan to automate this kind of audit. It scans your source files to find env vars you're reading in code but haven't added to your .env.example or documentation. The audit above took me a few hours of manual GitHub API calls. envscan does it in seconds. Early access at ckmtools.dev/envscan/.

Which package surprised you? Drop it in the comments.

I Analyzed the Readability of 10 Popular Developer Documentation Sites

ckmtools — Fri, 20 Mar 2026 20:18:02 +0000

Good documentation is worth nothing if developers can't read it. I ran 10 popular developer docs pages through standard readability formulas—Flesch-Kincaid, Flesch Reading Ease, Gunning Fog—to see which ones actually write at a level humans can parse. The results were more consistent than I expected, with one glaring outlier.

The Methodology

Three formulas, all derived from word length and sentence length:

Flesch Reading Ease: 0–100 scale, higher is easier. 60–70 is considered standard/plain English. Anything below 30 is classified as very difficult (think academic journals or legal contracts).
Flesch-Kincaid Grade Level: Maps to US school grade levels. Grade 8 means an 8th grader can read it. Grade 12+ starts getting into college territory.
Gunning Fog Index: Similar grade-level metric, but also accounts for complex words (3+ syllables). Higher Fog = more jargon-dense text.

I fetched each page with requests, stripped code blocks, navigation, headers, footers, and sidebars with BeautifulSoup, then ran the remaining prose through Python's textstat library. Pages with fewer than 200 extractable words were skipped (two pages—Prisma and Express—fell into this category because their content is rendered client-side or split across tabs).

The Results

Documentation	Flesch Reading Ease	FK Grade Level	Gunning Fog	Assessment
GitHub REST API Docs	56.2	8.8	11.0	Fairly difficult
Stripe API Docs	54.0	9.4	11.3	Fairly difficult
Fastify Server Docs	53.3	9.2	10.9	Fairly difficult
Next.js Installation	52.9	8.6	10.5	Fairly difficult
Vercel Getting Started	52.0	10.0	10.9	Fairly difficult
Supabase Getting Started	49.3	11.0	12.9	Difficult
PlanetScale Docs	44.6	11.9	14.0	Difficult
Turso Docs	19.0	18.7	21.1	Very difficult
Prisma Getting Started	N/A	N/A	N/A	Failed to fetch: insufficient extractable text (client-side rendered)
Express Hello World	N/A	N/A	N/A	Failed to fetch: insufficient extractable text (<200 words)

Key Findings

The cluster is tight at the top. GitHub, Stripe, Fastify, Next.js, and Vercel all scored within 4 points of each other on Flesch Reading Ease (52–56). That's not a coincidence—mature, well-funded projects converge on similar writing patterns over time.
None of them hit the 60–70 "standard" range. Every site I measured scored "fairly difficult" or worse. Developer docs as a category skew harder than general web writing, likely because of technical terminology dragging up syllable counts.
Turso is in a different league. A Flesch Reading Ease of 19.0 and a Gunning Fog of 21.1 puts it solidly in the "very difficult" category—closer to academic papers than product documentation. The page analyzed (turso.tech/docs) appears to be a hub page with dense navigation text and product terminology rather than explanatory prose.
PlanetScale's conceptual docs are the most jargon-heavy of the narrative pages. A Gunning Fog of 14.0 suggests heavy use of multi-syllable technical terms throughout. The "What is PlanetScale" page covers database branching, non-blocking schema changes, and connection pooling—all of which pull the score down.

What Surprised Me

I expected GitHub's docs to score near the top—they have a dedicated technical writing team and it shows. But I didn't expect Stripe to be that close behind. Stripe's API reference page pulls in a lot of domain-specific vocabulary (idempotency, webhook, idempotent), yet the sentence structure is short and direct enough to offset the complexity.

Turso's score surprised me in the other direction. A 19.0 is genuinely unusual for a product landing/docs page. Some of it is measurement artifact—the page is thin on prose and heavy on navigation labels and feature names—but even accounting for that, it's an outlier. If Turso's conceptual overview pages score similarly, that's a usability gap worth addressing.

Why This Matters

Readability scores don't measure accuracy or completeness—you can have perfectly readable docs that are still wrong. But they do correlate with time-to-first-success: if your docs require a college reading level and your target developer is working late on a deadline, every extra sentence complexity is friction. The tight cluster at 52–56 among the top-tier tools suggests that's roughly where developer docs naturally land when written by experienced technical writers under editorial review.

The bigger gap is between that cluster (52–56) and the ideal range (60–70). No one in this sample hit plain-English territory. That's a realistic target for "getting started" and tutorial content, where the goal is onboarding rather than reference.

If you need to run this kind of analysis at scale—across docs sites, product pages, or user-generated content—the TextLens API (currently in early access waitlist at ckmtools.dev) handles text extraction and readability scoring via a single endpoint.

I Scanned 10 Popular GitHub Actions Workflows for Undocumented Environment Variables. Here's What I Found.

ckmtools — Thu, 19 Mar 2026 20:08:19 +0000

I Scanned 10 Popular GitHub Actions Workflows for Undocumented Environment Variables. Here's What I Found.

Every repo has GitHub Actions workflows. They're full of environment variables nobody documents. I spent an afternoon scanning 10 popular open-source JavaScript projects to find out how bad the problem really is.

What I Was Looking For

I was hunting for variables referenced in workflow YAML — ${{ secrets.VAR }}, env: blocks, hardcoded values — that appear nowhere in the project's README, .env.example, or CONTRIBUTING.md. The silent assumptions that break your fork on day one. The things maintainers know instinctively but never wrote down.

Methodology

I chose 10 projects that most JavaScript developers have at minimum heard of: Electron, NestJS, Next.js, Remix, Prisma, Supabase, Strapi, Fastify, TypeORM, and Vitest. For each, I fetched their workflow YAML files via the GitHub API and looked for env: blocks, ${{ secrets.* }} references, and any hardcoded values that looked like configuration. I then cross-checked against their README and CONTRIBUTING.md files. "Undocumented" means the variable name appears in no public documentation — not a sentence, not a comment, nothing.

The Findings

1. electron/electron

electron/electron — ★☆☆

Electron's build pipeline is understandably complex, but the env var situation is rough. CHROMIUM_GIT_COOKIE appears in nearly every workflow file — it's clearly essential for fetching the Chromium source — but there's no explanation of what it is, how to obtain it, or who manages it. The README has zero environment variable mentions. The contributing guide links to an external docs page.

The one that caught my eye: PATCH_UP_APP_CREDS. It shows up in the ARM/ARM64 Linux build job with zero context. Searching the repo reveals nothing useful. If you're trying to fork Electron's build pipeline, you'd have to ask in an issue and hope someone answers.

Also present: DD_API_KEY (Datadog) and CI_ERRORS_SLACK_WEBHOOK_URL — neither documented anywhere public.

2. nestjs/nest

nestjs/nest — ★★★

Honestly refreshing. NestJS has a single workflow file: codeql-analysis.yml. No custom secrets, no bespoke environment variables. Just the standard GITHUB_TOKEN. There's nothing to document because there's nothing unusual. This is what good hygiene looks like for a library project.

3. vercel/next.js

vercel/next.js — ★★☆

Next.js has the largest collection of environment variables of any project I looked at — and the README mentions zero of them. The build_reusable.yml alone defines 15+ env vars at the top level.

Most interesting cluster: three separate Vercel test tokens — VERCEL_TEST_TOKEN, VERCEL_ADAPTER_TEST_TOKEN, and VERCEL_TURBOPACK_TEST_TOKEN — each pointing to a different internal test team. The team names (vtest314-next-e2e-tests, vtest314-next-adapter-e2e-tests, vtest314-next-turbo-e2e-tests) suggest these are Vercel-internal accounts that nobody outside the org can replicate.

There's also KV_REST_API_URL and KV_REST_API_TOKEN (a Vercel KV store used for test timing data) and DATA_DOG_API_KEY — spelled differently from the DATADOG_API_KEY used in a separate job in the same file. Whether that inconsistency is intentional or a bug is unclear.

To be fair, some of this complexity is genuinely hard to document — it's infrastructure that only Vercel employees can operate. But a note explaining why these exist would help.

4. remix-run/remix

remix-run/remix — ★★★

The other clean result. Remix's build.yaml has zero environment variables. The check.yaml is equally bare. Their README focuses on library portability across JavaScript environments, which tracks with having almost no CI-specific secrets. If you fork Remix and run the CI, it should just work.

5. prisma/prisma

prisma/prisma — ★★☆

Prisma's README is actually solid — 12 mentions of environment variables, with clear docs on DATABASE_URL and how Prisma loads .env files. That's genuinely good documentation for library users.

The CI side is a different story. The release pipeline requires REDIS_URL — no explanation of what this Redis instance stores or where it lives. The benchmark workflow sets PRISMA_TELEMETRY_INFORMATION to the string 'prisma benchmark.yml' — an undocumented internal field that presumably tags telemetry events but isn't documented anywhere public. The release workflow also posts to Slack via SLACK_RELEASE_FEED_WEBHOOK and uses BOT_TOKEN (a personal access token, per an inline comment) for release tagging.

None of these are critical for contributors building features, but they mean you can't replicate the release process without asking.

6. supabase/supabase

supabase/supabase — ★☆☆

This one surprised me. Supabase requires OPENAI_API_KEY in two separate test workflows: ai-tests.yml and studio-e2e-test.yml. There's also a braintrust-evals.yml that pulls in BRAINTRUST_PROJECT_ID and BRAINTRUST_API_KEY for running LLM evaluations as part of CI.

The README has zero environment variable mentions. The CONTRIBUTING.md mentions "inclusive environment" and that's it. If you're a contributor who wants to run the full test suite, you need three external service accounts (OpenAI, Braintrust, Vercel) that are never mentioned in any onboarding document.

The CONTRIBUTING.md is 2,454 characters total. It links to a code of conduct and a Slack. That's all.

7. strapi/strapi

strapi/strapi — ★★☆

Strapi actually documents one of its important env vars: STRAPI_LICENSE gets a sentence in CONTRIBUTING.md explaining that contributors need it to run Enterprise Edition tests. Credit where it's due.

The rest is less tidy. SONARQUBE_HOST_URL is stored as a secret — not just the token, but the URL itself — which suggests they're running a private SonarQube instance. TRUNK_API_TOKEN appears for the trunk.io lint service. RELEASE_APP_ID and RELEASE_APP_SECRET power a GitHub App used for releases, with no public documentation on which app or why a dedicated one is needed.

The README is completely silent on all of this.

8. fastify/fastify

fastify/fastify — ★★★

Fastify is minimal and clean. The CI uses NODE_OPTIONS: no-network-family-autoselection in the TypeScript test jobs — an undocumented flag that presumably addresses some network behavior in the test environment — but that's the only non-obvious thing. No custom secrets beyond GITHUB_TOKEN. No unexplained infrastructure dependencies. If you fork Fastify, CI will work.

9. typeorm/typeorm

typeorm/typeorm — ★★☆

TypeORM's notable env vars are CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID, used to deploy their documentation to Cloudflare Pages. These are CI infrastructure secrets that you wouldn't need as a code contributor, but they're also never mentioned — not even a comment in the workflow file explaining what they deploy to or why. A line like # Deploys docs to Cloudflare Pages project 'typeorm' would answer every question.

The preview workflow has zero env vars. The codeql analysis has none either. Relatively clean overall.

10. vitest-dev/vitest

vitest-dev/vitest — ★★☆

Vitest sets VITEST_GENERATE_UI_TOKEN: 'true' as a global env var across the entire CI. This isn't documented in the README, the CONTRIBUTING, or the public docs. Based on context, it appears to control whether Vitest generates a token for its UI panel during test runs — but what that token is used for and why it's enabled in CI specifically isn't explained.

PLAYWRIGHT_BROWSERS_PATH is a standard Playwright caching pattern — acceptable. No external secrets required, which means forks can run the full test suite without any extra configuration.

Summary

Project	Workflow Files	Env Vars Found	Secrets Found	README Docs	Doc Quality
electron/electron	15+	2	5	0 mentions	★☆☆
nestjs/nest	1	0	0	0 mentions	★★★
vercel/next.js	5+	15	11	0 mentions	★★☆
remix-run/remix	5+	0	0	3 mentions	★★★
prisma/prisma	18	2	4	12 mentions	★★☆
supabase/supabase	40+	0	4	0 mentions	★☆☆
strapi/strapi	22	2	6	0 mentions	★★☆
fastify/fastify	5	1	1	0 mentions	★★★
typeorm/typeorm	5	0	2	1 mention	★★☆
vitest-dev/vitest	6	2	0	0 mentions	★★☆

Patterns Worth Noting

The infrastructure-as-secret problem. Several projects store URLs as secrets, not just tokens — Strapi's SONARQUBE_HOST_URL is the clearest example. This is reasonable from a security standpoint (you don't want to advertise your internal tooling endpoints), but it means contributors can't understand the CI pipeline from reading the YAML alone.

Third-party service sprawl. Supabase requires OpenAI and Braintrust accounts to run the full test suite. Next.js requires Vercel-internal accounts that literally no external contributor can create. When your CI has hard dependencies on services that only your org controls, you've effectively made full CI reproduction impossible for outsiders — and none of these projects acknowledge this in their contributing docs.

The "works if you're an employee" problem. The most undocumented variables tend to be the ones that are only relevant to the maintainer doing releases or running internal benchmarks. This makes sense — they never break for contributors building features. But it creates a knowledge silo. When you eventually need to run that release pipeline or onboard a new maintainer, the documentation doesn't exist.

Why This Matters

If you're maintaining a Node.js or Python project and want to audit your own repo for exactly this kind of gap, I've been building a tool called envscan that scans your codebase for environment variables used in code, workflow files, and configuration — then flags which ones are missing from .env.example or any documentation. You can check it out and get early access at envscan.ckmtools.dev. It's free while I'm validating the idea.

Have a project with surprisingly good env var docs? Drop it in the comments — I'd genuinely like to see it.

Text Analysis in Go Without a Machine Learning Library

ckmtools — Wed, 18 Mar 2026 19:46:41 +0000

Go's standard library handles strings and Unicode well. strings.Fields, unicode.IsLetter, bufio.Scanner — you can build word count and basic stats without any third-party packages. Where the ecosystem gets thin is content quality metrics: readability grades, sentiment scoring, keyword extraction.

If you've worked with Python's textstat, textblob, or spacy, you've seen how much ground is already covered there. Go is a different story.

The Go NLP Landscape

Go does have some text processing packages worth knowing:

github.com/jdkato/prose is the most complete option. It handles tokenization, part-of-speech tagging, and named entity recognition. Solid for linguistic analysis, but it doesn't cover readability grades (Flesch-Kincaid, Gunning Fog, Coleman-Liau) or AFINN sentiment scoring.

Built-in strings and unicode packages get you word counts, sentence boundaries (if you're careful about punctuation), and character-level stats. You can compute a rough syllable count heuristic from there. But "rough" is doing a lot of work in that sentence — the standard readability formulas need accurate syllable counts, and Go has no widely-used syllabification package.

The honest summary: Go NLP is early-stage compared to Python for content quality metrics specifically. If you need Flesch-Kincaid grade, SMOG index, sentiment polarity, and TF-IDF keywords from a single call, there's no Go package that covers all of that. You'd be writing it from scratch or stitching together multiple immature libraries.

A REST API Sidestep

For content quality metrics, an HTTP endpoint sidesteps the library problem. The Go HTTP client is first-class — this pattern is idiomatic and unsurprising to anyone reading the code:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

type AnalysisResult struct {
    Readability struct {
        ConsensusGrade string  `json:"consensus_grade"`
        FleschKincaid  float64 `json:"flesch_kincaid_grade"`
    } `json:"readability"`
    Sentiment struct {
        Label string  `json:"label"`
        Score float64 `json:"score"`
    } `json:"sentiment"`
    Keywords struct {
        Top5 []string `json:"top_5"`
    } `json:"keywords"`
}

func analyzeText(apiKey, text string) (*AnalysisResult, error) {
    body, err := json.Marshal(map[string]string{"text": text})
    if err != nil {
        return nil, err
    }
    req, err := http.NewRequest("POST", "https://api.ckmtools.dev/v1/analyze", bytes.NewBuffer(body))
    if err != nil {
        return nil, err
    }
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", apiKey)

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result AnalysisResult
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, err
    }
    return &result, nil
}

func main() {
    result, err := analyzeText(os.Getenv("TEXTLENS_KEY"), "Your content here...")
    if err != nil {
        fmt.Fprintf(os.Stderr, "error: %v\n", err)
        os.Exit(1)
    }
    fmt.Printf("Grade: %s, Sentiment: %s\n",
        result.Readability.ConsensusGrade,
        result.Sentiment.Label,
    )
}

The struct tags match the JSON response directly. Add fields as you need them. If you want FleschKincaid, GunningFog, SMOG, and ColemanLiau, expand the Readability struct — they're all in the response.

When This Pattern Makes Sense

This is worth considering if you're:

Building a blog platform, CMS, or content review tool in Go and you need readability grades before publishing
Running automated content quality checks in a CI pipeline
Building a tool that auto-tags content with extracted keywords
Writing a Go service that wraps text analysis for downstream consumers

The key constraint is that you don't want to maintain a Python sidecar or pull in a large dependency for a feature that isn't your core product.

Honest Tradeoff

HTTP adds 20–100ms per request. For most editorial workflows — "analyze this article before it goes live" — that's fine. For interactive writing tools with keypress-level feedback, it's noticeable. For batch processing thousands of documents per minute, a local library would be faster if one existed.

That last part is the constraint. For high-throughput stream processing in Go, a local library would be the right call. Right now, the Go ecosystem doesn't have one that covers these metrics. So you're choosing between HTTP overhead and writing the implementation yourself.

Where to Find This

The TextLens API is in development — free tier at 1,000 requests/month. Waitlist is open at ckmtools.dev/api/ if this fits a project you're working on. Feedback on the Go client structure is welcome — I'm particularly curious whether the struct tag approach is the interface people actually want or whether a map-based response is more practical for dynamic field access.

I Scanned 6 Popular Node.js Repos for Undocumented Environment Variables. Here's What I Found.

ckmtools — Wed, 18 Mar 2026 05:18:57 +0000

Most Node.js projects accumulate process.env references over time. Some document them in .env.example. Many don't. I wanted to know how bad the problem actually is in well-maintained, popular open-source repos — so I ran a search using the GitHub API.

Here's what I found.

The Repos

I picked six repos with different scopes: two minimal HTTP frameworks, one structured framework, two full-stack application platforms, and one backend-as-a-service:

Repo	Stars	Type
expressjs/express	~65k	HTTP framework
fastify/fastify	~32k	HTTP framework
nestjs/nest	~68k	Application framework
strapi/strapi	~63k	Headless CMS
keystonejs/keystone	~9k	Full-stack CMS
supabase/supabase	~73k	BaaS platform (monorepo)

For each repo I used the GitHub code search API to count process.env references, then checked for the presence of .env.example (or .env.sample, .env.template) files at the root and recursively.

Results

Repo	`process.env` refs	`.env.example` files	Coverage
expressjs/express	6	0	—
fastify/fastify	5	0	—
nestjs/nest	7	0	—
strapi/strapi	135	10	Partial
keystonejs/keystone	112	3	Partial
supabase/supabase	294	24	Best-in-class

What This Actually Means

The numbers don't tell the full story. The three frameworks at the top (express, fastify, nest) aren't slacking — they're libraries. Their process.env usage is intentionally minimal. Express reads NODE_ENV in lib/application.js. Fastify uses a few vars in test scripts and a serverless guide. NestJS delegates env config entirely to application code via @nestjs/config.

The bottom three are application platforms and CMS tools — products you self-host or deploy, where env configuration is core to the product. Their higher counts make sense.

Strapi: 135 refs, 10 .env.example files

The refs are spread across a large monorepo (packages/, examples/, scripts/). The examples each ship their own .env.example, but the core package doesn't have a central one. The most significant example — examples/complex/.env.example — contains exactly one line:

JWT_SECRET=replaceme

That's the entire documented env surface for a complex Strapi installation, despite the codebase referencing 135 env variables across all packages.

Keystone: 112 refs, 3 .env.example files

The .env.example files exist only for specific integration examples (S3 assets, Cloudinary). The docs/.env.example contains a single variable: BUTTONDOWN_API_KEY= — which is the newsletter API key for Keystone's own documentation site, not something users of the framework need.

Core application env vars (database URLs, session secrets) are documented in prose in the official docs, not as a discoverable example file.

Supabase: 294 refs, 24 .env.example files

Supabase is the standout here. The docker/.env.example is the most thorough example file I found across all six repos — it includes inline comments explaining what each variable does, links to docs for generating secrets, and even notes which values need to be rotated before going to production:

# YOU MUST CHANGE ALL THE DEFAULT VALUES BELOW BEFORE STARTING
# THE CONTAINERS FOR THE FIRST TIME!

That's the right way to do it. Still, the E2E test suite in e2e/studio/env.config.ts references vars like GITHUB_PASS, GITHUB_TOTP, VERCEL_AUTOMATION_BYPASS_SELFHOSTED_STUDIO, SUPA_PAT, and SUPA_REGION — none of which appear in any .env.example. These are CI/testing credentials that contributors need but have to discover by reading the source.

The Pattern

Across all six repos, a consistent pattern emerges:

Framework repos: Low env var count by design. Documentation isn't the problem — minimal surface is the point.

Application platform repos: High env var count, .env.example files exist but cover only a slice of the actual surface. The gap between documented and total process.env references can be large (strapi: 10 files documenting maybe 15 vars vs 135 total refs).

Test and CI env vars are almost never documented. Every repo with a test suite uses env vars to configure database URLs, API tokens, and service endpoints for testing. None of those showed up in .env.example files.

The Maintenance Problem

The real challenge isn't the initial .env.example — it's keeping it in sync as the codebase grows. A feature adds process.env.NEW_FEATURE_FLAG. The .env.example is a separate file. Nobody updates it because nothing enforces the connection.

In a small repo, this is fine. In a monorepo with 135+ references spread across packages and examples, it becomes hard to answer the question: "what env vars does this actually need?"

Wrapping Up

If you're dealing with this problem in your own codebase — especially if you've inherited a repo where nobody's sure what all the process.env references actually are — scanning the source files is the most reliable way to get a definitive list. I'm working on envscan, a tool that does exactly that: scans your source files to discover every env var your code references, and compares it against your .env.example. It's in development with a waitlist open if that sounds useful.

Data collected 2026-03-18 using the GitHub Code Search API. Counts reflect the state of the default branches at time of writing. Repos with monorepo structures may have higher counts due to cross-package test fixtures and build scripts.

Repos scanned: express, fastify, nest, strapi, keystone, supabase

I Compared 5 Python Text Analysis Libraries — Then Built a REST API Instead

ckmtools — Tue, 17 Mar 2026 21:02:39 +0000

When you need readability scores in Python, your first search turns up textstat. For sentiment, VADER. For keyword extraction, yake or keybert. For everything at once, you're running 3-4 libraries with their own install requirements, version conflicts, and update cycles.

I spent a few hours comparing the main options. Here's what I found — and why I ended up building a REST API instead.

The five main options

Library	What it does	Install size
textstat	Readability scoring (FK, Fog, SMOG, etc.)	Small
vaderSentiment	Sentiment for social media text	Small
TextBlob	Sentiment + NLP basics	Medium
NLTK	Full NLP toolkit	Large
spaCy	Production NLP	Large

What each one actually does

textstat is the go-to for readability. It gives you Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, ARI, and Dale-Chall in one call. PyPI shows it at around 218,000 downloads per week, which tells you there's a real use case here. What it doesn't do: sentiment, keywords, or anything beyond readability formulas.

import textstat

text = "The cat sat on the mat."
print(textstat.flesch_reading_ease(text))    # 116.15
print(textstat.gunning_fog(text))            # 0.8
print(textstat.flesch_kincaid_grade(text))   # -3.5

vaderSentiment (Valence Aware Dictionary and sEntiment Reasoner) is excellent at what it does: sentiment scoring on short, informal text. Tweets, product reviews, forum posts. It handles punctuation, capitalization, and emoticons. It's not designed for long-form content, and it doesn't touch readability.

from vaderSentiment.vaderSentiment import SentimentIntensityAnalyzer

analyzer = SentimentIntensityAnalyzer()
scores = analyzer.polarity_scores("This is absolutely terrible!")
print(scores)  # {'neg': 0.508, 'neu': 0.492, 'pos': 0.0, 'compound': -0.5849}

TextBlob gives you sentiment plus basic NLP (noun phrases, part-of-speech tagging). It wraps NLTK under the hood. The sentiment output is simpler than VADER — just polarity and subjectivity. No readability.

from textblob import TextBlob

blob = TextBlob("The food was good but the service was slow.")
print(blob.sentiment)  # Sentiment(polarity=0.3, subjectivity=0.6)

NLTK can do almost anything — tokenization, stemming, tagging, parsing, named entity recognition, sentiment — but it requires substantial setup and hand-coding. There's no nltk.analyze(text) call. You assemble what you need from primitives. NLTK sees about 13.7 million downloads per week, but a significant chunk of that is downstream dependencies pulling it in. The knowledge threshold to use it effectively is real.

spaCy is the best option for production NLP pipelines: dependency parsing, named entity recognition, word vectors, custom pipelines. It's also the heaviest. Model downloads range from 12MB (small English) to 560MB (large). For a "just give me a readability score" use case, it's significant overhead.

The problem isn't quality

Each of these libraries is good at what it does. The problem appears when you need more than one type of analysis in the same project.

Say you're building a content quality checker that needs readability grade, sentiment (is this copy too negative?), and keyword density. You're now installing:

pip install textstat vaderSentiment yake

Three separate install chains. Three sets of dependencies to keep in sync. If you're containerizing, all three go in the image. If you're on serverless with a 250MB limit, that fills up fast once spaCy's models are involved.

Version conflicts are the worst case. NLTK and spaCy both have opinions about numpy. If your environment already has numpy pinned for a different reason, you may be debugging dependency issues before you write a single line of analysis code.

The REST API approach

I built TextLens API to sidestep this entirely. The Python client is just requests:

import requests

result = requests.post(
    "https://api.ckmtools.dev/v1/analyze",
    headers={"X-API-Key": "your_key"},
    json={"text": "Your content here..."}
)
data = result.json()
print(data["readability"]["flesch_kincaid_grade"])
print(data["sentiment"]["compound"])
print(data["keywords"])

Readability, sentiment, and keywords in one response. Your dependency list stays at requests, which you probably already have.

The trade-off is real: there's HTTP latency on every call, and if you're processing thousands of documents per second, local libraries will always be faster.

When each approach makes sense

Use local libraries if:

You're processing large document volumes in batch (hundreds per second or more)
You have no outbound network access
You only need one type of metric and don't mind the single dependency

Use an API if:

Your stack includes multiple languages (Python service + Node.js frontend)
You want readability + sentiment + keywords without managing 3 separate library installs
You're prototyping and want to defer the dependency decision

The TextLens API waitlist

I'm building this for the second use case — one endpoint, three analysis types, free tier at 1,000 requests/month. The waitlist is at https://ckmtools.dev/api/ if you're in that situation. Early access is free; feedback on the API design is welcome.

The local libraries are all solid options when you need them. But if you've spent an afternoon debugging a numpy version conflict between textstat and spaCy, a 50ms API call starts looking pretty reasonable.

Why I Stopped Maintaining .env.example by Hand

ckmtools — Tue, 17 Mar 2026 03:01:54 +0000

Every Node.js project I've worked on has the same failure mode: a new developer clones the repo, runs npm install, tries to start the server, and gets a cryptic error because some environment variable is missing. .env.example is out of date. Again. Here's the tool I'm building to fix that.

The specific pain point

You add DATABASE_URL to your code on Tuesday. You forget to add it to .env.example. Three weeks later, someone's production deploy fails because they copied .env.example and missed the new variable.

The fix is always: "oh, add that to .env.example." Then you spend twenty minutes figuring out which variables are actually needed, checking the code, checking the deployment docs, hoping nothing was added after the last time someone updated the example file.

The real problem: nothing tells you .env.example is missing a variable until something breaks. The stale .env.example is a silent bug. It doesn't fail when you commit it. It fails three weeks later in someone else's environment.

Why existing tools don't solve it

There are good tools in this space. dotenv-safe has 152,609 downloads last week. envalid has 478,131. They work — but they're all declaration-first: you maintain a list of required variables in a schema file, and the tool validates your environment against that list.

The problem: maintaining the schema is the same work as maintaining .env.example. You still have to remember to update it every time you add a new process.env reference in your code. The schema can go stale for exactly the same reason .env.example goes stale — there's no enforcement, just discipline.

dotenv (91 million weekly downloads) solves loading. These tools solve validation against a declared schema. None of them solve the discovery problem: figuring out which vars your code actually needs.

The insight: the source code already knows

Every time you write process.env.DATABASE_URL in your code, you've implicitly declared that you need DATABASE_URL. That declaration is already there — it's just not extracted anywhere.

I'm building envscan to do that extraction. It scans your .js and .ts files and pulls out every process.env reference:

$ envscan scan
Found 8 environment variables:

  DATABASE_URL       type: url      src/db.ts:12
  PORT               type: number   src/server.ts:5
  JWT_SECRET         type: secret   src/auth.ts:8, src/auth.ts:23
  REDIS_URL          type: url      src/cache.ts:3
  SENDGRID_API_KEY   type: secret   src/email.ts:7
  APP_ENV            type: string   src/config.ts:2
  LOG_LEVEL          type: string   src/config.ts:3
  DEBUG              type: boolean  src/config.ts:4

Validation: 7/8 vars set. Missing: SENDGRID_API_KEY

No config file needed. No schema to maintain. The schema is the codebase.

The type inference is heuristic — it looks at variable names (_URL → url, _SECRET, _KEY, _TOKEN → secret, PORT → number, DEBUG → boolean) — but it's right often enough to be useful as a starting point.

What it generates

envscan generate writes a .env.example with type hints and source locations as comments:

# type: url | Found in: src/db.ts:12
DATABASE_URL=

# type: number | Found in: src/server.ts:5
PORT=

# type: secret | Found in: src/auth.ts:8
JWT_SECRET=

# type: url | Found in: src/cache.ts:3
REDIS_URL=

# type: secret | Found in: src/email.ts:7
SENDGRID_API_KEY=

# type: string | Found in: src/config.ts:2
APP_ENV=

# type: string | Found in: src/config.ts:3
LOG_LEVEL=

# type: boolean | Found in: src/config.ts:4
DEBUG=

Run it in a pre-commit hook. .env.example stays in sync automatically — not because someone remembered to update it, but because it's regenerated from the code.

The validate command compares your current environment against what the scan finds and reports what's missing. You can wire it into your startup script so the process fails loudly and immediately rather than failing cryptically three console.log calls later.

The CI angle (honest about what's not built yet)

The CLI is almost done. What I'm building next is a GitHub Action that runs envscan validate on every pull request and posts an inline comment when new process.env references appear in the diff without a matching .env.example entry — catching the stale .env.example problem before it merges.

That CI tier is the paid part ($6/month). Running GitHub Actions costs money, and I'd like to maintain this long-term rather than abandoning it when hosting costs add up. The CLI will stay free.

I haven't released either yet. The core scanning and generation works. The edge cases I'm still handling: template literals (process.env[key]), computed property access, and variables referenced only in test files. Computed access is genuinely hard — you can't statically know the variable name if it's dynamic. My current approach flags those as a warning rather than silently skipping them.

If this sounds useful

envscan isn't released yet — I'm finishing the CLI now. If this sounds like a problem you've run into, the waitlist is at ckmtools.dev/envscan/ — no credit card, just an email to get notified when it ships.

Feedback welcome on the output format. The file location comments in .env.example — useful or noisy? Let me know in the comments.

I Wrapped My Free npm Package as a Paid REST API — Here's the Architecture

ckmtools — Tue, 17 Mar 2026 02:16:51 +0000

textlens is a zero-dependency npm package for text analysis — readability scoring, sentiment analysis, keyword extraction. It's free. It always will be. But I keep getting the same question: "Do you have a Python version?" Here's what I built to answer that.

The problem npm doesn't solve

Node.js packages are invisible to Python developers, Ruby developers, PHP developers, and no-code tools like Zapier and Make.

textlens pulls 177 downloads/week and has 6 GitHub stars. That sounds modest, but the point is: that entire audience is JavaScript developers. Every one of them can npm install textlens and be running in 30 seconds. Everyone else is locked out.

Python has textstat, which gives you a single Flesch reading ease score. It has nltk for tokenization. What it doesn't have is an equivalent of textlens — 8 readability formulas, sentiment analysis, keyword extraction, and SEO-relevant metrics in a single call. Ruby has even less. PHP has nearly nothing. No-code tools like Zapier have no path to npm at all.

The REST API targets everyone else.

Why not just publish a Python wrapper?

I considered it. A Python package that calls the textlens npm package under the hood via subprocess. Or a direct Python reimplementation of the same algorithms.

Both are worse than a hosted API.

A subprocess wrapper means the user needs Node.js installed — which defeats the purpose entirely. A reimplementation means maintaining two codebases that can drift apart. When I add a new readability formula to the npm package, I'd have to duplicate the work in Python (and Ruby, and Go, and whatever comes next).

A hosted API solves this once:

import requests

result = requests.post(
    "https://api.ckmtools.dev/v1/analyze",
    headers={"X-API-Key": "your_key"},
    json={"text": "Your text here..."}
)
print(result.json()["readability"]["consensus_grade"])

One endpoint. Any HTTP client. Any language. No Node.js required.

Architecture decisions

Here's what runs where and why.

Cloudflare Workers (edge compute)

The API runs on Cloudflare Workers. The choice was between Workers, a traditional VPS, and a serverless platform like AWS Lambda.

Workers won on three criteria: sub-50ms response globally with zero cold starts, operational cost around $0.15/million requests, and — critically — they support bundling npm packages directly. The textlens package (github.com/ckmtools/textlens) gets compiled into the Worker bundle at deploy time. No separate service to maintain. No inter-service latency.

KV storage for API keys and rate limiting

Cloudflare KV stores API keys and rate limit counters. Keys are provisioned automatically via Stripe webhook: customer pays → webhook fires → key gets written to KV → customer gets their key by email.

The rate limiting is fixed-window per minute. Here's the honest trade-off: KV is eventually consistent. Two requests arriving simultaneously at different edge nodes could both "see" a counter below the limit and both succeed, briefly exceeding the rate limit. For a text analysis API, this is acceptable — it's not a financial transaction. I acknowledged this rather than pretending it doesn't exist.

Stripe for subscription management

Stripe handles the subscription lifecycle: checkout, upgrades, cancellations, failed payments. Webhooks drive key provisioning and revocation. The only manual step is the initial Stripe product/price setup.

This means I don't write payment processing code. Stripe does that. My webhook handler is about 40 lines.

Free tier: 1,000 requests/month, no credit card

The free tier exists for a real reason: developers don't commit budget to new tools without trying them. 1,000 requests is enough to build and test an integration. If you hit the limit, you know it's useful enough to pay for.

What this architecture costs to run

Cloudflare Workers requires their paid plan at $5/month for the KV namespace. That's the only standing cost. At $9/month for the Starter tier, the first subscriber covers hosting. This is not a money printer at small scale — it's a break-even tool that becomes profitable with volume.

The business model question

Wrapping a free npm package as a paid API requires honest justification.

The answer isn't "convenience" in the abstract. It's that Python/Ruby/no-code developers have no other option. The npm package has 177 downloads/week — that's real demand for text analysis tooling. The question is how many of those downloads come from developers who later discover they need the same capability in Python and hit a wall.

I don't know that number yet. That's what the waitlist is for.

17 articles about text analysis tooling later, with 359 total views on dev.to, there's clearly an audience that cares about this problem space. Whether enough of them are Python developers willing to pay $9/month is what validation answers.

What's next

The API is in development. If you work in Python, Ruby, or no-code tools and would use a hosted text analysis endpoint, the waitlist is at ckmtools.dev/api/ — free tier, no credit card.

Why I Built a Readability Analyzer That Sends Your Text Nowhere

ckmtools — Mon, 16 Mar 2026 22:46:39 +0000

Why I Built a Readability Analyzer That Sends Your Text Nowhere

Most productivity tools that analyze your writing send your text to a server. That's true of Grammarly. It's true of most AI writing assistants. And it's worth thinking about, because writers paste a lot of sensitive material into these tools — drafts of internal reports, client work, things under NDA, early chapters of books they haven't published yet.

ProseScore doesn't send your text anywhere. Here's why that was a deliberate choice, and what it took to make it work.

The problem with sending your text to a server

When you paste something into a web-based writing tool, you're implicitly trusting that tool with whatever you wrote. That might be fine for a recipe. It's different for a confidential internal memo, a legal brief draft, or a chapter from a novel you've been working on for two years.

The data minimization argument is simple: if you don't need a server, don't have one. A server is a liability — it's a place where data can be retained, subpoenaed, breached, or sold. Readability analysis doesn't require a server. It requires math. So I didn't build one.

What ProseScore actually does

The entire analysis runs in the browser. All of it — the 8 readability formulas, AFINN-based sentiment scoring, TF-IDF keyword extraction — executes synchronously in a Web Worker. The UI stays responsive even on long documents because the analysis runs off the main thread.

The code path looks roughly like this:

// Everything runs here, client-side
const result = analyzeText(inputText);
// No network call. No tracking. Just math.

There are no fetch() calls anywhere in the analysis path. The only network request the page makes is the initial page load. After that, you can take your browser offline and it keeps working — because it's not waiting for anything.

The Web Worker approach was worth the extra complexity. Without it, analyzing a 5,000-word document would lock the UI for a noticeable fraction of a second. With it, the interface stays interactive while the analysis runs in the background.

Why 8 readability formulas work offline

Not all NLP tasks are created equal. Sentiment analysis at scale usually means embeddings, which means models, which means GPU time on a server somewhere. That's a legitimate reason to send text to a server.

Readability scoring is different. Flesch-Kincaid, Gunning Fog, SMOG, Coleman-Liau, ARI, Dale-Chall, Linsear Write — these are pure algorithmic formulas. They operate on word counts, sentence lengths, and syllable counts. No ML models. No embeddings. No hardware requirements beyond whatever CPU is in the person's laptop.

The irony is that readability scoring is one of the few NLP tasks that was basically designed for offline computation. These formulas were developed in an era before networked computers. They're deterministic. Given the same input, every browser produces the same score.

ProseScore computes all 8 formulas and derives a consensus grade level from the results. Running eight formulas instead of one doesn't meaningfully change the performance profile — they're all operating on the same precomputed word/sentence/syllable counts.

What surprised me

Two things caught me off guard during the build.

The first was syllable counting. It sounds trivial. It isn't. English doesn't have a clean algorithmic rule for syllables — the exceptions are numerous, and naive implementations that count vowel runs get wrong answers constantly. I ended up with a heuristic that handles common patterns and exceptions, and it's good enough for readability scoring, but it's not perfect. Don't use it to settle poetry arguments.

The second was deriving the consensus grade level. Each of the 8 formulas uses a different scale. Flesch-Kincaid outputs a US grade level. Flesch Reading Ease runs 0-100 in the opposite direction (higher = easier). SMOG and Gunning Fog have their own calibrations. To combine them into a single consensus grade, I had to understand what each formula was actually measuring, not just run the equations. That took longer than the implementation itself.

The catch

No server means no persistence. There's no history. No way to compare your score on this draft against the version you edited last Tuesday. No sharing. No team dashboards. If you close the tab, the analysis is gone.

For personal writing and private documents, that's fine — it's actually the point. For teams that want to track readability trends across a documentation repo over time, ProseScore isn't the right tool. That use case requires a server. I'm not pretending otherwise.

The trade-off is intentional: ProseScore does one thing — analyze text you paste into it, right now, without that text leaving your browser. It doesn't try to be everything.

The tool is at prosescore.ckmtools.dev — open source, MIT license. If you're curious about the implementation, the full source is at github.com/ckmtools/prosescore.

How I Got 6 GitHub Stars Without a Launch Event

ckmtools — Mon, 16 Mar 2026 16:32:40 +0000

6 GitHub stars doesn't sound like much. But I didn't run a Show HN. I didn't launch on Product Hunt. I didn't email any newsletters. I just published an npm package and watched what drove people to the GitHub repo. The source of those stars surprised me.

The setup

textlens is a zero-dependency text analysis library for Node.js. It launched March 4. One command gets you Flesch-Kincaid readability scores, sentiment analysis, keyword extraction, and sentence statistics — no API calls, no setup, no config file.

npm install textlens

const textlens = require('textlens');
const result = textlens.analyze('Your text here.');
console.log(result.readability.fleschKincaid); // { grade: 8.1, readingEase: 62 }

As of today: 6 GitHub stars, 82 npm downloads this week, 15 dev.to articles totaling 355 views.

What I expected to drive stars

The strategy going in: publish a lot of dev.to content, get readers, convert some to GitHub stars.

I published 15 articles over 12 days. 355 total views. My best performer — "I Built a Free Hemingway Editor Alternative That Runs in Your Terminal" — hit 122 views on its own. I expected dev.to to be the main driver.

I also did a Product Hunt launch. 3 upvotes. I don't count that as a meaningful signal.

A Show HN was planned but never happened. The queue felt premature.

What GitHub referrer data actually showed

Here's the 14-day referrer table, pulled directly from the GitHub traffic API:

Referrer	Views	Unique visitors
echojs.com	36	18
github.com	32	3
ckmtools.dev	22	3
Google	6	6
npmjs.com	2	1
Bing	1	1

Echo JS is the top external traffic source by unique visitors. Not dev.to. Not Hacker News. Not Reddit. Echo JS.

The traffic pattern made the picture clearer. On March 10, GitHub views spiked to 23 unique visitors in a single day — that's more than the entire previous week combined. Days 11 and 12 stayed elevated. Those three days account for the majority of the 18 unique Echo JS visitors.

Stars went from 1 to 6 during that same 72-hour window.

dev.to sent 0 visitors to github.com/ckmtools/textlens despite 300+ article views.

Why Echo JS worked

Echo JS (echojs.com) is a developer news aggregator focused specifically on JavaScript. It's small, text-only, and curated. The audience is developers browsing for something interesting to look at — usually during work.

The difference from dev.to is the context. On dev.to, people read articles. On Echo JS, people discover things. When someone lands on Echo JS, they're in "what should I click?" mode. They follow links. They open GitHub repos. They star things they want to remember.

dev.to has the views but not the click-through. 122 views on my Hemingway article meant 122 people read the article. Almost none of them navigated to GitHub. The call-to-action worked fine inside dev.to's reading environment — it just didn't convert to GitHub behavior.

Echo JS has fewer views, but the viewers are primed to act on what they find.

What this changed about my strategy

Before looking at the referrer data, I was optimizing for dev.to views. After, I changed four things:

Submit every article to Echo JS within the same hour of publishing. The traffic spike is time-sensitive — the front page moves fast, and visibility drops after a few hours.
Write for discovery, not volume. One article that lands on Echo JS's front page outperforms ten articles that don't.
Include 3+ GitHub links per article. Reader intent matters less than surface area. More links = more chances someone navigates over.
Track GitHub referrers from day 1. npm downloads tell you about installs. GitHub referrers tell you about intent. They measure different things.

The npm download data (82 downloads this week) is encouraging, but it doesn't tell me where the interest is coming from. The referrer data does.

The takeaway

A zero-star package is invisible. Getting to 6 wasn't about volume or luck — it was about finding the channel where the right kind of attention lands.

If you're building an npm package and only tracking npm downloads, add GitHub referrer data to your monitoring. The distribution of traffic sources will probably surprise you.

More of what I've been building: github.com/ckmtools/textlens