Spaces:
Sleeping
Sleeping
File size: 4,658 Bytes
9f069df | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 | #!/usr/bin/env node
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { join, relative } from "node:path";
process.stdout.on("error", (error) => {
if (error?.code === "EPIPE") {
process.exit(0);
}
throw error;
});
const DOCS_DIR = join(process.cwd(), "docs");
if (!existsSync(DOCS_DIR)) {
console.error("docs:list: missing docs directory. Run from repo root.");
process.exit(1);
}
if (!statSync(DOCS_DIR).isDirectory()) {
console.error("docs:list: docs path is not a directory.");
process.exit(1);
}
const EXCLUDED_DIRS = new Set(["archive", "research"]);
/**
* @param {unknown[]} values
* @returns {string[]}
*/
function compactStrings(values) {
const result = [];
for (const value of values) {
if (value === null || value === undefined) {
continue;
}
const normalized =
typeof value === "string"
? value.trim()
: typeof value === "number" || typeof value === "boolean"
? String(value).trim()
: null;
if (normalized?.length > 0) {
result.push(normalized);
}
}
return result;
}
/**
* @param {string} dir
* @param {string} base
* @returns {string[]}
*/
function walkMarkdownFiles(dir, base = dir) {
const entries = readdirSync(dir, { withFileTypes: true });
const files = [];
for (const entry of entries) {
if (entry.name.startsWith(".")) {
continue;
}
const fullPath = join(dir, entry.name);
if (entry.isDirectory()) {
if (EXCLUDED_DIRS.has(entry.name)) {
continue;
}
files.push(...walkMarkdownFiles(fullPath, base));
} else if (entry.isFile() && entry.name.endsWith(".md")) {
files.push(relative(base, fullPath));
}
}
return files.toSorted((a, b) => a.localeCompare(b));
}
/**
* @param {string} fullPath
* @returns {{ summary: string | null; readWhen: string[]; error?: string }}
*/
function extractMetadata(fullPath) {
const content = readFileSync(fullPath, "utf8");
if (!content.startsWith("---")) {
return { summary: null, readWhen: [], error: "missing front matter" };
}
const endIndex = content.indexOf("\n---", 3);
if (endIndex === -1) {
return { summary: null, readWhen: [], error: "unterminated front matter" };
}
const frontMatter = content.slice(3, endIndex).trim();
const lines = frontMatter.split("\n");
let summaryLine = null;
const readWhen = [];
let collectingField = null;
for (const rawLine of lines) {
const line = rawLine.trim();
if (line.startsWith("summary:")) {
summaryLine = line;
collectingField = null;
continue;
}
if (line.startsWith("read_when:")) {
collectingField = "read_when";
const inline = line.slice("read_when:".length).trim();
if (inline.startsWith("[") && inline.endsWith("]")) {
try {
const parsed = JSON.parse(inline.replace(/'/g, '"'));
if (Array.isArray(parsed)) {
readWhen.push(...compactStrings(parsed));
}
} catch {
// ignore malformed inline arrays
}
}
continue;
}
if (collectingField === "read_when") {
if (line.startsWith("- ")) {
const hint = line.slice(2).trim();
if (hint) {
readWhen.push(hint);
}
} else if (line === "") {
// allow blank lines inside the list
} else {
collectingField = null;
}
}
}
if (!summaryLine) {
return { summary: null, readWhen, error: "summary key missing" };
}
const summaryValue = summaryLine.slice("summary:".length).trim();
const normalized = summaryValue
.replace(/^['"]|['"]$/g, "")
.replace(/\s+/g, " ")
.trim();
if (!normalized) {
return { summary: null, readWhen, error: "summary is empty" };
}
return { summary: normalized, readWhen };
}
console.log("Listing all markdown files in docs folder:");
const markdownFiles = walkMarkdownFiles(DOCS_DIR);
for (const relativePath of markdownFiles) {
const fullPath = join(DOCS_DIR, relativePath);
const { summary, readWhen, error } = extractMetadata(fullPath);
if (summary) {
console.log(`${relativePath} - ${summary}`);
if (readWhen.length > 0) {
console.log(` Read when: ${readWhen.join("; ")}`);
}
} else {
const reason = error ? ` - [${error}]` : "";
console.log(`${relativePath}${reason}`);
}
}
console.log(
'\nReminder: keep docs up to date as behavior changes. When your task matches any "Read when" hint above (React hooks, cache directives, database work, tests, etc.), read that doc before coding, and suggest new coverage when it is missing.',
);
|