readme-guide 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023-2026 是 Ray 不是 Array
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,47 @@
1
- # Temporary Holding Version
1
+ # readme-guide
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Checks a README against the [README Guide](https://readme-guide.com): eight blocks in a fixed order, commands and versions that match the project, nothing left unfinished. Zero dependencies; needs Node.js 22 or later.
4
+
5
+ [繁體中文說明](https://readme-guide.com/zh-tw/)
6
+
7
+ ## Usage
8
+
9
+ ```bash
10
+ npx readme-guide@latest check README.md
11
+ ```
12
+
13
+ The checker compares the README with the files in its folder (`package.json`, the lock file, `.env.example`, `LICENSE` and so on). Every problem comes with a rule ID, a line number and how to fix it.
14
+
15
+ To look up one rule in full:
16
+
17
+ ```bash
18
+ npx readme-guide@latest explain CMD004
19
+ ```
20
+
21
+ ## Options
22
+
23
+ | Option | What it does |
24
+ | --- | --- |
25
+ | `--type <type>` | Project type: `web-app`, `course-example`, `portfolio` or `backend-api`. Detected when omitted. |
26
+ | `--lang <lang>` | Output language: `zh-TW` or `en`. Same as the README when omitted. |
27
+ | `--project <folder>` | Project folder to compare against. Defaults to the README's folder. |
28
+ | `--json` | Print JSON for AI or other tools to read. |
29
+ | `-h`, `--help` | Show the help. |
30
+
31
+ `explain` accepts only `--lang` and `--json`.
32
+
33
+ ## Exit codes
34
+
35
+ | Code | Meaning |
36
+ | --- | --- |
37
+ | `0` | No errors (there may be warnings). |
38
+ | `1` | At least one error. |
39
+ | `2` | Bad options, a missing file, or an unknown rule ID. |
40
+
41
+ ## Learn more
42
+
43
+ The rules, templates and the guide for AI are on [readme-guide.com](https://readme-guide.com) ([繁體中文](https://readme-guide.com/zh-tw/)).
44
+
45
+ ## License
46
+
47
+ [MIT](https://github.com/hsiangfeng/readme-guide/blob/main/LICENSE)
@@ -0,0 +1,125 @@
1
+ #!/usr/bin/env node
2
+ // readme-guide 指令列:照 README Guide 的規則檢查一份 README,或查一條規則的說明。
3
+ // 用法:readme-guide check [README 路徑] [--type 類型] [--lang zh-TW|en] [--json] [--project 資料夾]
4
+ // readme-guide explain <規則代號> [--lang zh-TW|en] [--json]
5
+ // 在 repo 裡開發時用 node lint/bin/readme-guide.mjs 執行。
6
+ import { readFileSync, existsSync, statSync } from 'node:fs';
7
+ import path from 'node:path';
8
+ import { parseArgs } from 'node:util';
9
+ import { lintReadme } from '../src/lint.js';
10
+ import { fsProject } from '../src/project.js';
11
+ import { formatHuman, formatJson } from '../src/format.js';
12
+ import { TYPE_IDS, LANGS } from '../src/data.js';
13
+ import { findRule, describeRule, formatRule, unknownRuleMessage, similarRules } from '../src/explain.js';
14
+
15
+ const HELP = {
16
+ 'zh-TW': `用法:
17
+ readme-guide check [README 路徑] [選項]
18
+ readme-guide explain <規則代號> [--lang zh-TW|en] [--json]
19
+
20
+ check 照 README Guide 的八塊結構與規則檢查 README。README 路徑沒給時,用目前資料夾的 README.md。
21
+ explain 印出一條規則的完整說明(屬於哪一塊、嚴重度、說明、怎麼修),例如 readme-guide explain CMD004。
22
+
23
+ 選項:
24
+ --type <類型> 專案類型:${TYPE_IDS.join('、')}(沒給就自動判斷)
25
+ --lang <語言> 輸出語言:zh-TW 或 en(沒給就跟 README 的語言一樣)
26
+ --project <資料夾> 專案資料夾,用來對照 package.json、.env.example 等檔案(預設是 README 所在的資料夾)
27
+ --json 輸出給 AI 讀的 JSON
28
+ -h, --help 顯示這段說明
29
+
30
+ 結束代碼:有錯誤是 1;只有警告或沒有問題是 0;參數或檔案有問題、找不到規則是 2。`,
31
+ en: `Usage:
32
+ readme-guide check [README path] [options]
33
+ readme-guide explain <RULE_ID> [--lang zh-TW|en] [--json]
34
+
35
+ check reviews a README against the README Guide's eight blocks and rules. Without a path it checks README.md in the current folder.
36
+ explain prints one rule in full (block, severity, description, how to fix), for example readme-guide explain CMD004.
37
+
38
+ Options:
39
+ --type <type> Project type: ${TYPE_IDS.join(', ')} (detected when omitted)
40
+ --lang <lang> Output language: zh-TW or en (same as the README when omitted)
41
+ --project <folder> Project folder, used to compare against package.json, .env.example and so on (defaults to the README's folder)
42
+ --json Print JSON for AI to read
43
+ -h, --help Show this help
44
+
45
+ Exit code: 1 when there are errors; 0 with only warnings or no problems; 2 for bad options, a missing file or an unknown rule.`,
46
+ };
47
+
48
+ function fail(message) {
49
+ process.stderr.write(`${message}\n`);
50
+ process.exit(2);
51
+ }
52
+
53
+ function guessLang(argv) {
54
+ const index = argv.indexOf('--lang');
55
+ const value = index !== -1 ? argv[index + 1] : argv.find((a) => a.startsWith('--lang='))?.split('=')[1];
56
+ if (LANGS.includes(value)) return value;
57
+ return /^zh/i.test(process.env.LANG ?? '') ? 'zh-TW' : 'en';
58
+ }
59
+
60
+ const argv = process.argv.slice(2);
61
+ const uiLang = guessLang(argv);
62
+ let parsed;
63
+ try {
64
+ parsed = parseArgs({
65
+ args: argv,
66
+ allowPositionals: true,
67
+ options: {
68
+ type: { type: 'string' },
69
+ lang: { type: 'string' },
70
+ json: { type: 'boolean', default: false },
71
+ project: { type: 'string' },
72
+ help: { type: 'boolean', short: 'h', default: false },
73
+ },
74
+ });
75
+ } catch (error) {
76
+ fail(`${error.message}\n\n${HELP[uiLang]}`);
77
+ }
78
+
79
+ const { values, positionals } = parsed;
80
+ if (values.help || positionals.length === 0) {
81
+ process.stdout.write(`${HELP[uiLang]}\n`);
82
+ process.exit(values.help ? 0 : 2);
83
+ }
84
+ const [command, target = 'README.md', ...extra] = positionals;
85
+ if (values.lang && !LANGS.includes(values.lang)) fail(uiLang === 'en' ? '--lang must be zh-TW or en' : '--lang 只能是 zh-TW 或 en');
86
+
87
+ if (command === 'explain') {
88
+ if (positionals.length !== 2) fail(uiLang === 'en' ? `Give exactly one rule ID, for example: readme-guide explain CMD004\n\n${HELP.en}` : `請給一個規則代號,例如:readme-guide explain CMD004\n\n${HELP['zh-TW']}`);
89
+ if (values.type || values.project) fail(uiLang === 'en' ? 'explain takes only --lang and --json' : 'explain 只接受 --lang 與 --json');
90
+ const lang = values.lang ?? uiLang;
91
+ const rule = findRule(target);
92
+ if (!rule) {
93
+ if (values.json) {
94
+ process.stdout.write(`${JSON.stringify({ error: 'unknown-rule', id: target, similar: similarRules(target) }, null, 2)}\n`);
95
+ process.exit(2);
96
+ }
97
+ fail(unknownRuleMessage(target, lang));
98
+ }
99
+ process.stdout.write(`${values.json ? JSON.stringify(describeRule(rule, lang), null, 2) : formatRule(rule, lang)}\n`);
100
+ process.exit(0);
101
+ }
102
+
103
+ if (command !== 'check' || extra.length) fail(uiLang === 'en' ? `Unknown command: ${positionals.join(' ')}\n\n${HELP.en}` : `看不懂的指令:${positionals.join(' ')}\n\n${HELP['zh-TW']}`);
104
+ if (values.type && !TYPE_IDS.includes(values.type)) fail(uiLang === 'en' ? `--type must be one of: ${TYPE_IDS.join(', ')}` : `--type 只能是:${TYPE_IDS.join('、')}`);
105
+
106
+ const readmeAbs = path.resolve(target);
107
+ if (!existsSync(readmeAbs) || !statSync(readmeAbs).isFile()) fail(uiLang === 'en' ? `File not found: ${target}` : `找不到檔案:${target}`);
108
+ const projectDir = path.resolve(values.project ?? path.dirname(readmeAbs));
109
+ if (!existsSync(projectDir) || !statSync(projectDir).isDirectory()) fail(uiLang === 'en' ? `Project folder not found: ${values.project}` : `找不到專案資料夾:${values.project}`);
110
+
111
+ const result = lintReadme({
112
+ text: readFileSync(readmeAbs, 'utf8'),
113
+ project: fsProject(projectDir),
114
+ readmePath: path.relative(projectDir, readmeAbs).split(path.sep).join('/'),
115
+ type: values.type,
116
+ lang: values.lang,
117
+ });
118
+
119
+ if (values.json) {
120
+ process.stdout.write(`${formatJson(target, projectDir, result)}\n`);
121
+ } else {
122
+ const color = process.stdout.isTTY && !process.env.NO_COLOR;
123
+ process.stdout.write(`${formatHuman(target, result, { color })}\n`);
124
+ }
125
+ process.exit(result.summary.errors > 0 ? 1 : 0);
package/package.json CHANGED
@@ -1,6 +1,45 @@
1
1
  {
2
2
  "name": "readme-guide",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Check a README against the README Guide: eight blocks in a fixed order, verified commands and versions, nothing left unfinished. Zero dependencies.",
5
+ "keywords": [
6
+ "readme",
7
+ "documentation",
8
+ "lint",
9
+ "linter",
10
+ "markdown",
11
+ "cli",
12
+ "checker"
13
+ ],
14
+ "homepage": "https://readme-guide.com",
15
+ "bugs": {
16
+ "url": "https://github.com/hsiangfeng/readme-guide/issues"
17
+ },
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/hsiangfeng/readme-guide.git",
21
+ "directory": "lint"
22
+ },
23
+ "license": "MIT",
24
+ "author": {
25
+ "name": "Ray",
26
+ "url": "https://israynotarray.com"
27
+ },
28
+ "type": "module",
29
+ "bin": {
30
+ "readme-guide": "bin/readme-guide.mjs"
31
+ },
32
+ "files": [
33
+ "bin/",
34
+ "src/",
35
+ "rules/*.json"
36
+ ],
37
+ "engines": {
38
+ "node": ">=22"
39
+ },
40
+ "scripts": {
41
+ "test": "node --test",
42
+ "prepack": "node scripts/bundle-rules.mjs copy",
43
+ "postpack": "node scripts/bundle-rules.mjs clean"
44
+ }
45
+ }
@@ -0,0 +1,123 @@
1
+ {
2
+ "groups": [
3
+ {
4
+ "id": "what",
5
+ "question": {
6
+ "zh-TW": "這是什麼?",
7
+ "en": "What is it?"
8
+ }
9
+ },
10
+ {
11
+ "id": "run",
12
+ "question": {
13
+ "zh-TW": "怎麼跑起來?",
14
+ "en": "How do I run it?"
15
+ }
16
+ },
17
+ {
18
+ "id": "change",
19
+ "question": {
20
+ "zh-TW": "怎麼改、能不能用?",
21
+ "en": "How do I change it, and may I use it?"
22
+ }
23
+ }
24
+ ],
25
+ "blocks": [
26
+ {
27
+ "slug": "title",
28
+ "group": "what",
29
+ "name": {
30
+ "zh-TW": "標題與一句話說明",
31
+ "en": "Title and one-line description"
32
+ },
33
+ "summary": {
34
+ "zh-TW": "第一行是全文唯一的一級標題;下一行用一句純文字說明做什麼、給誰用;再一行寫專案狀態。",
35
+ "en": "The first line is the only top-level heading; the next line says in one plain sentence what it does and who it is for; then one line with the project status."
36
+ }
37
+ },
38
+ {
39
+ "slug": "demo",
40
+ "group": "what",
41
+ "name": {
42
+ "zh-TW": "線上展示與畫面",
43
+ "en": "Demo and screenshots"
44
+ },
45
+ "summary": {
46
+ "zh-TW": "線上網址與截圖。圖片要有替代文字,重點不能只放在圖裡。",
47
+ "en": "Live link and screenshots. Every image needs alt text, and nothing important should live only inside an image."
48
+ }
49
+ },
50
+ {
51
+ "slug": "features",
52
+ "group": "what",
53
+ "name": {
54
+ "zh-TW": "功能",
55
+ "en": "Features"
56
+ },
57
+ "summary": {
58
+ "zh-TW": "做得到的事;還沒做的可以標出來。",
59
+ "en": "What it can do; things not built yet can be marked as such."
60
+ }
61
+ },
62
+ {
63
+ "slug": "tech",
64
+ "group": "what",
65
+ "name": {
66
+ "zh-TW": "使用技術",
67
+ "en": "Tech stack"
68
+ },
69
+ "summary": {
70
+ "zh-TW": "只寫主要框架與主版號。",
71
+ "en": "Only the main frameworks and their major versions."
72
+ }
73
+ },
74
+ {
75
+ "slug": "install",
76
+ "group": "run",
77
+ "name": {
78
+ "zh-TW": "安裝與執行",
79
+ "en": "Getting started"
80
+ },
81
+ "summary": {
82
+ "zh-TW": "環境需求(寫版本)、安裝步驟、執行測試(選填);指令放程式碼區塊。",
83
+ "en": "Requirements (with versions), installation steps, running tests (optional); commands go in code blocks."
84
+ }
85
+ },
86
+ {
87
+ "slug": "env",
88
+ "group": "run",
89
+ "name": {
90
+ "zh-TW": "環境變數",
91
+ "en": "Environment variables"
92
+ },
93
+ "summary": {
94
+ "zh-TW": "每個變數的用途、是否必填、去哪裡拿;不放真的金鑰。",
95
+ "en": "What each variable is for, whether it is required and where to get it; never a real key."
96
+ }
97
+ },
98
+ {
99
+ "slug": "structure",
100
+ "group": "change",
101
+ "name": {
102
+ "zh-TW": "資料夾結構",
103
+ "en": "Project structure"
104
+ },
105
+ "summary": {
106
+ "zh-TW": "只列重要的一兩層。",
107
+ "en": "Only the one or two levels that matter."
108
+ }
109
+ },
110
+ {
111
+ "slug": "license",
112
+ "group": "change",
113
+ "name": {
114
+ "zh-TW": "作者、聯絡與授權",
115
+ "en": "Author, contact and license"
116
+ },
117
+ "summary": {
118
+ "zh-TW": "「作者與聯絡」與「授權」是兩個標題,「授權」固定放最後;「貢獻方式」選填,放在這兩個之前。公開的專案要寫授權,公司內部或不公開的專案可以不寫;「作者與聯絡」一定要有,內部專案就寫負責的團隊和有問題要去哪裡問。",
119
+ "en": "\"Author\" and \"License\" are two separate headings, and \"License\" always comes last; \"Contributing\" is optional and goes before both. Public projects state a license; internal or private projects may leave it out. \"Author\" is always required: for an internal project, name the team that owns it and where to ask questions."
120
+ }
121
+ }
122
+ ]
123
+ }
@@ -0,0 +1,39 @@
1
+ {
2
+ "placeholder": {
3
+ "pattern": "\\{\\{\\s*(?:請填|FILL)[^}]*\\}\\}",
4
+ "flags": "gi",
5
+ "examples": {
6
+ "zh-TW": "{{請填:專案名稱}}",
7
+ "en": "{{FILL: project name}}"
8
+ },
9
+ "note": {
10
+ "zh-TW": "範本裡每個要填的地方都用雙大括號包起來,開頭寫「請填:」(英文範本寫「FILL:」)。成品裡留下任何一個,檢查工具都會報錯(STR015)。在網址或指令裡的待填處不要有空白,例如 {{請填:帳號}}、{{FILL:owner}}。",
11
+ "en": "Every blank in a template is wrapped in double curly braces and starts with \"FILL:\" (\"請填:\" in Traditional Chinese templates). Any one left in a finished README is an error (STR015). Inside a link or a command, keep it free of spaces, for example {{FILL:owner}}."
12
+ },
13
+ "syntaxMention": {
14
+ "pattern": "^\\{\\{\\s*(?:請填|FILL)\\s*[::]?\\s*(?:…|\\.{3})\\s*\\}\\}$",
15
+ "flags": "i",
16
+ "note": {
17
+ "zh-TW": "說明只有刪節號的 {{請填:…}}、{{FILL: ...}},是在介紹這個寫法本身,不是還沒填的地方,檢查工具不報。範本裡真正的待填處一定要寫說明文字。",
18
+ "en": "A blank whose description is only an ellipsis, such as {{FILL: …}} or {{請填:...}}, is talking about the syntax itself, not a missing value, so the checker does not report it. Real blanks in templates always carry a description."
19
+ }
20
+ }
21
+ },
22
+ "oneLiner": {
23
+ "maxLength": { "zh-TW": 60, "en": 120 },
24
+ "note": {
25
+ "zh-TW": "中文以字計(一個英文單字算一個字),英文以字元計。",
26
+ "en": "Chinese is counted in characters (an English word counts as one), English in characters."
27
+ }
28
+ },
29
+ "status": {
30
+ "prefixes": {
31
+ "zh-TW": ["狀態", "專案狀態"],
32
+ "en": ["Status", "Project status"]
33
+ },
34
+ "values": {
35
+ "zh-TW": ["開發中", "已完成", "維護中", "練習用", "不再維護", "已停止維護", "已封存"],
36
+ "en": ["In development", "Completed", "Maintained", "Practice project", "No longer maintained", "Actively maintained", "Work in progress", "Archived", "Deprecated", "Unmaintained"]
37
+ }
38
+ }
39
+ }