@marcozvd/basics-core 0.0.0-stage → 1.2.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 +21 -0
- package/README.md +60 -2
- package/dist/activity.d.ts +17 -0
- package/dist/activity.d.ts.map +1 -0
- package/dist/activity.js +57 -0
- package/dist/activity.js.map +1 -0
- package/dist/api.d.ts +180 -0
- package/dist/api.d.ts.map +1 -0
- package/dist/api.js +2 -0
- package/dist/api.js.map +1 -0
- package/dist/config.d.ts +20 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +43 -0
- package/dist/config.js.map +1 -0
- package/dist/detect.d.ts +20 -0
- package/dist/detect.d.ts.map +1 -0
- package/dist/detect.js +199 -0
- package/dist/detect.js.map +1 -0
- package/dist/embeddings.d.ts +7 -0
- package/dist/embeddings.d.ts.map +1 -0
- package/dist/embeddings.js +2 -0
- package/dist/embeddings.js.map +1 -0
- package/dist/eval.d.ts +53 -0
- package/dist/eval.d.ts.map +1 -0
- package/dist/eval.js +46 -0
- package/dist/eval.js.map +1 -0
- package/dist/export.d.ts +22 -0
- package/dist/export.d.ts.map +1 -0
- package/dist/export.js +128 -0
- package/dist/export.js.map +1 -0
- package/dist/fsutil.d.ts +4 -0
- package/dist/fsutil.d.ts.map +1 -0
- package/dist/fsutil.js +39 -0
- package/dist/fsutil.js.map +1 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +20 -0
- package/dist/index.js.map +1 -0
- package/dist/negation.d.ts +17 -0
- package/dist/negation.d.ts.map +1 -0
- package/dist/negation.js +119 -0
- package/dist/negation.js.map +1 -0
- package/dist/outcome.d.ts +20 -0
- package/dist/outcome.d.ts.map +1 -0
- package/dist/outcome.js +102 -0
- package/dist/outcome.js.map +1 -0
- package/dist/packs.d.ts +119 -0
- package/dist/packs.d.ts.map +1 -0
- package/dist/packs.js +557 -0
- package/dist/packs.js.map +1 -0
- package/dist/query.d.ts +129 -0
- package/dist/query.d.ts.map +1 -0
- package/dist/query.js +484 -0
- package/dist/query.js.map +1 -0
- package/dist/schema.d.ts +252 -0
- package/dist/schema.d.ts.map +1 -0
- package/dist/schema.js +114 -0
- package/dist/schema.js.map +1 -0
- package/dist/tar.d.ts +27 -0
- package/dist/tar.d.ts.map +1 -0
- package/dist/tar.js +153 -0
- package/dist/tar.js.map +1 -0
- package/dist/templates.d.ts +15 -0
- package/dist/templates.d.ts.map +1 -0
- package/dist/templates.js +71 -0
- package/dist/templates.js.map +1 -0
- package/dist/trust.d.ts +5 -0
- package/dist/trust.d.ts.map +1 -0
- package/dist/trust.js +36 -0
- package/dist/trust.js.map +1 -0
- package/dist/vault-meta.d.ts +17 -0
- package/dist/vault-meta.d.ts.map +1 -0
- package/dist/vault-meta.js +49 -0
- package/dist/vault-meta.js.map +1 -0
- package/dist/vault.d.ts +66 -0
- package/dist/vault.d.ts.map +1 -0
- package/dist/vault.js +273 -0
- package/dist/vault.js.map +1 -0
- package/dist/vector-index.d.ts +41 -0
- package/dist/vector-index.d.ts.map +1 -0
- package/dist/vector-index.js +236 -0
- package/dist/vector-index.js.map +1 -0
- package/package.json +39 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 MarcozVD
|
|
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,61 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @marcozvd/basics-core
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Core library behind [Basics](https://github.com/MarcozVD/basics): a personal tech-stack knowledge vault
|
|
4
|
+
(Markdown + frontmatter + `[[wikilinks]]`) that your coding agents read and extend.
|
|
5
|
+
|
|
6
|
+
It provides vault parsing and validation, the v2 note schema (layer, tech, practice, check, profile, project),
|
|
7
|
+
full-text search, keyword and hybrid stack recommendation, markdown context rendering, atomic writes with
|
|
8
|
+
hash-based conflict detection, global config resolution, and the shared API types used by the CLI, HTTP API and web UI.
|
|
9
|
+
|
|
10
|
+
## Install
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
npm install @marcozvd/basics-core
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Requires Node.js >= 20.11.
|
|
17
|
+
|
|
18
|
+
## Usage
|
|
19
|
+
|
|
20
|
+
```ts
|
|
21
|
+
import { Vault, recommend, renderContext } from "@marcozvd/basics-core";
|
|
22
|
+
|
|
23
|
+
const vault = Vault.load("./examples/vault"); // throws VaultNotFoundError if missing
|
|
24
|
+
const rec = recommend(vault, "REST API to serve ML models", { layers: ["backend", "data"] });
|
|
25
|
+
|
|
26
|
+
console.log(rec.layers.backend.map((c) => `${c.id} (${c.score})`)); // ranked candidates + why they matched
|
|
27
|
+
console.log(rec.note); // reminder: scores are a shortlist, the agent decides
|
|
28
|
+
|
|
29
|
+
// Markdown bundle ready for an agent or a project's STACK.md
|
|
30
|
+
const markdown = renderContext(vault, ["fastapi", "postgresql"]);
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## API overview
|
|
34
|
+
|
|
35
|
+
- **Vault** — `Vault.load(dir)` reads every note and validates it; `vault.get(id)`, `vault.byType(type)`,
|
|
36
|
+
`vault.techInLayer(layer)` and `vault.getBacklinks(id)` query it. `vault.writeNote(id, data, body, { expectedHash })`
|
|
37
|
+
writes atomically and throws `ConflictError` when the file changed on disk; `deleteNote` and `reload` complete the cycle.
|
|
38
|
+
- **Inbox** — `vault.propose(...)`, `listProposals()`, `approve(id)`, `approveAll({ pack, version })` and `reject(id)`
|
|
39
|
+
implement the agent-proposal workflow.
|
|
40
|
+
- **Search and navigation** — `search(vault, query)`, `listNotes(vault, { type, layer })`, `buildGraph(vault)`
|
|
41
|
+
and `vaultStats(vault)`.
|
|
42
|
+
- **Recommendation** — `recommend(vault, description, opts)` ranks candidates per layer with a score breakdown;
|
|
43
|
+
`recommendHybrid(...)` adds a local embedding score; `renderContext(vault, techIds)` and `stackContext(...)` render
|
|
44
|
+
markdown for agents and project files.
|
|
45
|
+
- **Projects** — `detectStack(vault, dir)` reads `package.json`, `pyproject.toml` and `requirements*.txt`;
|
|
46
|
+
`renderExport(...)` builds `STACK.md`, `AGENTS.md`, `CLAUDE.md` and Cursor rules; `inRange(version, since, until)`
|
|
47
|
+
filters versioned practices and checks.
|
|
48
|
+
- **Schema and config** — `noteSchema`, `noteJsonSchemas()`, `NOTE_TYPES`, `TYPE_DIRS`, `loadConfig()`,
|
|
49
|
+
`resolveVaultDir()`, plus pack helpers (`listPacks`, `installPack`, `updatePack`).
|
|
50
|
+
|
|
51
|
+
## Docs
|
|
52
|
+
|
|
53
|
+
Full documentation: [marcozvd.github.io/basics](https://marcozvd.github.io/basics/)
|
|
54
|
+
|
|
55
|
+
- [Concepts](https://marcozvd.github.io/basics/guide/concepts.html)
|
|
56
|
+
- [Vault schema reference](https://marcozvd.github.io/basics/reference/schema.html)
|
|
57
|
+
- [Stability contract](https://marcozvd.github.io/basics/guide/stability.html)
|
|
58
|
+
|
|
59
|
+
## License
|
|
60
|
+
|
|
61
|
+
MIT — see [LICENSE](https://github.com/MarcozVD/basics/blob/main/LICENSE).
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export interface ActivityEvent {
|
|
2
|
+
ts: string;
|
|
3
|
+
agent: string;
|
|
4
|
+
tool: string;
|
|
5
|
+
noteIds: string[];
|
|
6
|
+
detail?: string;
|
|
7
|
+
}
|
|
8
|
+
export declare function activityPath(root: string): string;
|
|
9
|
+
/** Create `<root>/.basics` with the gitignore that keeps local state out of the vault repo. */
|
|
10
|
+
export declare function basicsDir(root: string): string;
|
|
11
|
+
export declare function appendActivity(root: string, ev: Omit<ActivityEvent, "ts">): void;
|
|
12
|
+
export declare function readActivity(root: string, opts?: {
|
|
13
|
+
limit?: number;
|
|
14
|
+
noteId?: string;
|
|
15
|
+
agent?: string;
|
|
16
|
+
}): ActivityEvent[];
|
|
17
|
+
//# sourceMappingURL=activity.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAOD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,+FAA+F;AAC/F,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM9C;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,GAAG,IAAI,CAehF;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,aAAa,EAAE,CAmB1H"}
|
package/dist/activity.js
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import { atomicWrite } from "./fsutil.js";
|
|
4
|
+
const MAX_BYTES = 512 * 1024;
|
|
5
|
+
const KEEP_LINES = 1000;
|
|
6
|
+
const DEFAULT_LIMIT = 50;
|
|
7
|
+
const MAX_DETAIL = 120;
|
|
8
|
+
export function activityPath(root) {
|
|
9
|
+
return path.join(root, ".basics", "activity.jsonl");
|
|
10
|
+
}
|
|
11
|
+
/** Create `<root>/.basics` with the gitignore that keeps local state out of the vault repo. */
|
|
12
|
+
export function basicsDir(root) {
|
|
13
|
+
const dir = path.join(root, ".basics");
|
|
14
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
15
|
+
const gitignore = path.join(dir, ".gitignore");
|
|
16
|
+
if (!fs.existsSync(gitignore))
|
|
17
|
+
fs.writeFileSync(gitignore, "*\n");
|
|
18
|
+
return dir;
|
|
19
|
+
}
|
|
20
|
+
export function appendActivity(root, ev) {
|
|
21
|
+
const file = activityPath(root);
|
|
22
|
+
basicsDir(root);
|
|
23
|
+
const event = {
|
|
24
|
+
ts: new Date().toISOString(),
|
|
25
|
+
...ev,
|
|
26
|
+
detail: ev.detail?.slice(0, MAX_DETAIL),
|
|
27
|
+
};
|
|
28
|
+
fs.appendFileSync(file, `${JSON.stringify(event)}\n`);
|
|
29
|
+
if (fs.statSync(file).size > MAX_BYTES) {
|
|
30
|
+
const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
|
|
31
|
+
atomicWrite(file, `${lines.slice(-KEEP_LINES).join("\n")}\n`);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
export function readActivity(root, opts = {}) {
|
|
35
|
+
const file = activityPath(root);
|
|
36
|
+
if (!fs.existsSync(file))
|
|
37
|
+
return [];
|
|
38
|
+
const events = [];
|
|
39
|
+
for (const line of fs.readFileSync(file, "utf8").split("\n")) {
|
|
40
|
+
if (!line.trim())
|
|
41
|
+
continue;
|
|
42
|
+
try {
|
|
43
|
+
const parsed = JSON.parse(line);
|
|
44
|
+
if (typeof parsed.ts !== "string" || typeof parsed.agent !== "string" || typeof parsed.tool !== "string")
|
|
45
|
+
continue;
|
|
46
|
+
if (!Array.isArray(parsed.noteIds))
|
|
47
|
+
continue;
|
|
48
|
+
events.push(parsed);
|
|
49
|
+
}
|
|
50
|
+
catch {
|
|
51
|
+
// Ignore malformed lines so a partial write never breaks the feed.
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
const filtered = events.filter((ev) => (!opts.noteId || ev.noteIds.includes(opts.noteId)) && (!opts.agent || ev.agent === opts.agent));
|
|
55
|
+
return filtered.reverse().slice(0, opts.limit ?? DEFAULT_LIMIT);
|
|
56
|
+
}
|
|
57
|
+
//# sourceMappingURL=activity.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"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"}
|
package/dist/api.d.ts
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
import type { ExportTarget } from "./export.js";
|
|
2
|
+
import type { NoteData, NoteType, ProposalMeta } from "./schema.js";
|
|
3
|
+
export interface NoteSummary {
|
|
4
|
+
id: string;
|
|
5
|
+
type: NoteType;
|
|
6
|
+
title: string;
|
|
7
|
+
layers: string[];
|
|
8
|
+
kind?: string;
|
|
9
|
+
source: string;
|
|
10
|
+
updated?: string;
|
|
11
|
+
tags: string[];
|
|
12
|
+
/** First `use_when` entry for tech notes, else the first non-heading body line (max 120 chars). */
|
|
13
|
+
excerpt?: string;
|
|
14
|
+
/** Full project frontmatter for project notes, so the Projects list needs one request. */
|
|
15
|
+
project?: Extract<NoteData, {
|
|
16
|
+
type: "project";
|
|
17
|
+
}>;
|
|
18
|
+
}
|
|
19
|
+
export interface LayerSummary {
|
|
20
|
+
id: string;
|
|
21
|
+
title: string;
|
|
22
|
+
techs: string[];
|
|
23
|
+
}
|
|
24
|
+
export interface NoteDetail {
|
|
25
|
+
id: string;
|
|
26
|
+
type: NoteType;
|
|
27
|
+
data: NoteData;
|
|
28
|
+
body: string;
|
|
29
|
+
links: string[];
|
|
30
|
+
backlinks: string[];
|
|
31
|
+
hash: string;
|
|
32
|
+
path: string;
|
|
33
|
+
}
|
|
34
|
+
export interface ProposalSummary {
|
|
35
|
+
id: string;
|
|
36
|
+
type: NoteType;
|
|
37
|
+
title: string;
|
|
38
|
+
meta: ProposalMeta;
|
|
39
|
+
}
|
|
40
|
+
export interface ProposalDetail {
|
|
41
|
+
id: string;
|
|
42
|
+
meta: ProposalMeta;
|
|
43
|
+
data: NoteData;
|
|
44
|
+
body: string;
|
|
45
|
+
proposedText: string;
|
|
46
|
+
current: {
|
|
47
|
+
data: NoteData;
|
|
48
|
+
body: string;
|
|
49
|
+
hash: string;
|
|
50
|
+
text: string;
|
|
51
|
+
} | null;
|
|
52
|
+
}
|
|
53
|
+
export interface BrokenLink {
|
|
54
|
+
from: string;
|
|
55
|
+
to: string;
|
|
56
|
+
}
|
|
57
|
+
export interface VaultStats {
|
|
58
|
+
counts: Record<NoteType, number>;
|
|
59
|
+
total: number;
|
|
60
|
+
inbox: number;
|
|
61
|
+
brokenLinks: BrokenLink[];
|
|
62
|
+
orphans: string[];
|
|
63
|
+
/** Six most recently updated notes. */
|
|
64
|
+
recent: NoteSummary[];
|
|
65
|
+
}
|
|
66
|
+
export interface SaveNoteRequest {
|
|
67
|
+
data: NoteData;
|
|
68
|
+
body: string;
|
|
69
|
+
expectedHash?: string;
|
|
70
|
+
}
|
|
71
|
+
export interface CreateNoteRequest {
|
|
72
|
+
id: string;
|
|
73
|
+
data: NoteData;
|
|
74
|
+
body: string;
|
|
75
|
+
}
|
|
76
|
+
export interface ApproveRequest {
|
|
77
|
+
data?: NoteData;
|
|
78
|
+
body?: string;
|
|
79
|
+
}
|
|
80
|
+
export interface PackInstallRequest {
|
|
81
|
+
lang?: "en" | "es";
|
|
82
|
+
}
|
|
83
|
+
export interface PackInstallResult {
|
|
84
|
+
installed: string[];
|
|
85
|
+
skipped: string[];
|
|
86
|
+
/** Per-pack note ids, in install order. */
|
|
87
|
+
byPack: Record<string, {
|
|
88
|
+
installed: string[];
|
|
89
|
+
skipped: string[];
|
|
90
|
+
}>;
|
|
91
|
+
}
|
|
92
|
+
export interface PackUpdateResult {
|
|
93
|
+
proposed: string[];
|
|
94
|
+
unchanged: string[];
|
|
95
|
+
/** Installed notes the pack no longer owns (their source belongs to something else). */
|
|
96
|
+
skipped: string[];
|
|
97
|
+
upToDate: boolean;
|
|
98
|
+
}
|
|
99
|
+
export interface PackAddRequest {
|
|
100
|
+
repo: string;
|
|
101
|
+
ref?: string;
|
|
102
|
+
path?: string;
|
|
103
|
+
lang?: "en" | "es";
|
|
104
|
+
}
|
|
105
|
+
export interface PackAddResult {
|
|
106
|
+
name: string;
|
|
107
|
+
version: string;
|
|
108
|
+
repo: string;
|
|
109
|
+
ref: string;
|
|
110
|
+
proposed_new: string[];
|
|
111
|
+
proposed_changed: string[];
|
|
112
|
+
unchanged: string[];
|
|
113
|
+
skipped: string[];
|
|
114
|
+
/** Invalid notes skipped and reported (file + reason). */
|
|
115
|
+
invalid: {
|
|
116
|
+
file: string;
|
|
117
|
+
reason: string;
|
|
118
|
+
}[];
|
|
119
|
+
upToDate?: boolean;
|
|
120
|
+
}
|
|
121
|
+
export interface ApproveAllRequest {
|
|
122
|
+
pack: string;
|
|
123
|
+
version?: string;
|
|
124
|
+
}
|
|
125
|
+
export interface ApproveAllResponse {
|
|
126
|
+
approved: string[];
|
|
127
|
+
}
|
|
128
|
+
export interface RecommendRequest {
|
|
129
|
+
description: string;
|
|
130
|
+
layers?: string[];
|
|
131
|
+
perLayer?: number;
|
|
132
|
+
}
|
|
133
|
+
export interface ContextRequest {
|
|
134
|
+
techIds: string[];
|
|
135
|
+
}
|
|
136
|
+
export interface ContextResponse {
|
|
137
|
+
markdown: string;
|
|
138
|
+
}
|
|
139
|
+
export interface ExportRequest {
|
|
140
|
+
stack: string[];
|
|
141
|
+
targets?: ExportTarget[];
|
|
142
|
+
/** Current file contents keyed by relative path, merged into agent files. */
|
|
143
|
+
existing?: Record<string, string>;
|
|
144
|
+
}
|
|
145
|
+
export interface ApiError {
|
|
146
|
+
error: "conflict" | "invalid" | "not_found" | "vault_not_found" | "exists" | "forbidden" | "internal";
|
|
147
|
+
message: string;
|
|
148
|
+
actualHash?: string;
|
|
149
|
+
issues?: unknown;
|
|
150
|
+
hint?: string;
|
|
151
|
+
}
|
|
152
|
+
export type VaultEvent = {
|
|
153
|
+
type: "vault";
|
|
154
|
+
paths: string[];
|
|
155
|
+
} | {
|
|
156
|
+
type: "activity";
|
|
157
|
+
} | {
|
|
158
|
+
type: "embeddings";
|
|
159
|
+
done: number;
|
|
160
|
+
total: number;
|
|
161
|
+
};
|
|
162
|
+
export type GraphNodeType = NoteType | "missing";
|
|
163
|
+
export interface GraphNode {
|
|
164
|
+
id: string;
|
|
165
|
+
type: GraphNodeType;
|
|
166
|
+
title: string;
|
|
167
|
+
layers: string[];
|
|
168
|
+
/** Number of distinct neighbours among the returned edges. */
|
|
169
|
+
degree: number;
|
|
170
|
+
}
|
|
171
|
+
export interface GraphEdge {
|
|
172
|
+
source: string;
|
|
173
|
+
target: string;
|
|
174
|
+
kind: "link" | "broken";
|
|
175
|
+
}
|
|
176
|
+
export interface GraphData {
|
|
177
|
+
nodes: GraphNode[];
|
|
178
|
+
edges: GraphEdge[];
|
|
179
|
+
}
|
|
180
|
+
//# sourceMappingURL=api.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
|
package/dist/api.js
ADDED
package/dist/api.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":""}
|
package/dist/config.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
export declare const configSchema: z.ZodObject<{
|
|
3
|
+
vault: z.ZodOptional<z.ZodString>;
|
|
4
|
+
language: z.ZodDefault<z.ZodEnum<{
|
|
5
|
+
en: "en";
|
|
6
|
+
es: "es";
|
|
7
|
+
}>>;
|
|
8
|
+
embeddings: z.ZodDefault<z.ZodBoolean>;
|
|
9
|
+
embeddingsModel: z.ZodDefault<z.ZodString>;
|
|
10
|
+
}, z.core.$strip>;
|
|
11
|
+
export type Config = z.infer<typeof configSchema>;
|
|
12
|
+
/** Config file location: $BASICS_CONFIG or ~/.config/basics/config.json (same on Windows). */
|
|
13
|
+
export declare function configPath(): string;
|
|
14
|
+
export declare const DEFAULT_VAULT: string;
|
|
15
|
+
export declare function loadConfig(): Config;
|
|
16
|
+
export declare function saveConfig(cfg: Config): void;
|
|
17
|
+
export declare function expandHome(p: string): string;
|
|
18
|
+
/** Precedence: explicit > $BASICS_DIR > config "vault" > ~/basics-vault. */
|
|
19
|
+
export declare function resolveVaultDir(explicit?: string): string;
|
|
20
|
+
//# sourceMappingURL=config.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,YAAY;;;;;;;;iBAKvB,CAAC;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,8FAA8F;AAC9F,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,eAAO,MAAM,aAAa,EAAE,MAAgD,CAAC;AAE7E,wBAAgB,UAAU,IAAI,MAAM,CAQnC;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAI5C;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzD"}
|
package/dist/config.js
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import os from "node:os";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
import { atomicWrite } from "./fsutil.js";
|
|
6
|
+
export const configSchema = z.object({
|
|
7
|
+
vault: z.string().optional(),
|
|
8
|
+
language: z.enum(["en", "es"]).default("en"),
|
|
9
|
+
embeddings: z.boolean().default(false),
|
|
10
|
+
embeddingsModel: z.string().default("Xenova/multilingual-e5-small"),
|
|
11
|
+
});
|
|
12
|
+
/** Config file location: $BASICS_CONFIG or ~/.config/basics/config.json (same on Windows). */
|
|
13
|
+
export function configPath() {
|
|
14
|
+
return process.env.BASICS_CONFIG ?? path.join(os.homedir(), ".config", "basics", "config.json");
|
|
15
|
+
}
|
|
16
|
+
export const DEFAULT_VAULT = path.join(os.homedir(), "basics-vault");
|
|
17
|
+
export function loadConfig() {
|
|
18
|
+
const file = configPath();
|
|
19
|
+
if (!fs.existsSync(file))
|
|
20
|
+
return configSchema.parse({});
|
|
21
|
+
try {
|
|
22
|
+
return configSchema.parse(JSON.parse(fs.readFileSync(file, "utf8")));
|
|
23
|
+
}
|
|
24
|
+
catch (err) {
|
|
25
|
+
throw new Error(`Invalid config at ${file}: ${err instanceof Error ? err.message : String(err)}`);
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
export function saveConfig(cfg) {
|
|
29
|
+
atomicWrite(configPath(), `${JSON.stringify(cfg, null, 2)}\n`);
|
|
30
|
+
}
|
|
31
|
+
export function expandHome(p) {
|
|
32
|
+
if (p === "~")
|
|
33
|
+
return os.homedir();
|
|
34
|
+
if (p.startsWith("~/") || p.startsWith("~\\"))
|
|
35
|
+
return path.join(os.homedir(), p.slice(2));
|
|
36
|
+
return p;
|
|
37
|
+
}
|
|
38
|
+
/** Precedence: explicit > $BASICS_DIR > config "vault" > ~/basics-vault. */
|
|
39
|
+
export function resolveVaultDir(explicit) {
|
|
40
|
+
const dir = explicit ?? process.env.BASICS_DIR ?? loadConfig().vault ?? DEFAULT_VAULT;
|
|
41
|
+
return path.resolve(expandHome(dir));
|
|
42
|
+
}
|
|
43
|
+
//# sourceMappingURL=config.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;IAC5C,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACtC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,8BAA8B,CAAC;CACpE,CAAC,CAAC;AAGH,8FAA8F;AAC9F,MAAM,UAAU,UAAU;IACxB,OAAO,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC;AAClG,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAW,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,cAAc,CAAC,CAAC;AAE7E,MAAM,UAAU,UAAU;IACxB,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;IAC1B,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACvE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpG,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,WAAW,CAAC,UAAU,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC;IACnC,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1F,OAAO,CAAC,CAAC;AACX,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,eAAe,CAAC,QAAiB;IAC/C,MAAM,GAAG,GAAG,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,UAAU,EAAE,CAAC,KAAK,IAAI,aAAa,CAAC;IACtF,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC"}
|
package/dist/detect.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { Vault } from "./vault.js";
|
|
2
|
+
export interface DetectedTech {
|
|
3
|
+
id: string;
|
|
4
|
+
version?: string;
|
|
5
|
+
source: string;
|
|
6
|
+
}
|
|
7
|
+
export interface UnknownPackage {
|
|
8
|
+
ecosystem: "npm" | "pypi";
|
|
9
|
+
name: string;
|
|
10
|
+
version?: string;
|
|
11
|
+
}
|
|
12
|
+
export interface DetectResult {
|
|
13
|
+
techs: DetectedTech[];
|
|
14
|
+
unknown: UnknownPackage[];
|
|
15
|
+
files: string[];
|
|
16
|
+
}
|
|
17
|
+
/** Minimum version of a declaration, for either ecosystem. */
|
|
18
|
+
export declare function inRange(version: string | undefined, since?: string, until?: string): boolean;
|
|
19
|
+
export declare function detectStack(vault: Vault, dir: string): DetectResult;
|
|
20
|
+
//# sourceMappingURL=detect.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,KAAK,GAAG,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAyED,8DAA8D;AAC9D,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAQ5F;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CA+GnE"}
|
package/dist/detect.js
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
import semver from "semver";
|
|
4
|
+
import { parse as parseToml } from "smol-toml";
|
|
5
|
+
const NPM_FILE = "package.json";
|
|
6
|
+
const PYPROJECT_FILE = "pyproject.toml";
|
|
7
|
+
const REQUIREMENTS_FILE = "requirements.txt";
|
|
8
|
+
const REQUIREMENTS_DEV_FILE = "requirements-dev.txt";
|
|
9
|
+
/** PEP 503 normalization for Python package names. */
|
|
10
|
+
function normalizePypi(name) {
|
|
11
|
+
return name.toLowerCase().replace(/[-_.]+/g, "-");
|
|
12
|
+
}
|
|
13
|
+
function techIndex(vault) {
|
|
14
|
+
const index = { npm: new Map(), pypi: new Map(), ids: new Set(), databases: new Set() };
|
|
15
|
+
for (const note of vault.byType("tech")) {
|
|
16
|
+
const tech = note.data;
|
|
17
|
+
index.ids.add(note.id);
|
|
18
|
+
if (tech.kind === "database")
|
|
19
|
+
index.databases.add(note.id);
|
|
20
|
+
for (const name of tech.packages?.npm ?? [])
|
|
21
|
+
index.npm.set(name, note.id);
|
|
22
|
+
for (const name of tech.packages?.pypi ?? [])
|
|
23
|
+
index.pypi.set(normalizePypi(name), note.id);
|
|
24
|
+
}
|
|
25
|
+
return index;
|
|
26
|
+
}
|
|
27
|
+
function lookup(ecosystem, name, index) {
|
|
28
|
+
const key = ecosystem === "pypi" ? normalizePypi(name) : name;
|
|
29
|
+
const mapped = ecosystem === "npm" ? index.npm.get(key) : index.pypi.get(key);
|
|
30
|
+
if (mapped)
|
|
31
|
+
return mapped;
|
|
32
|
+
return index.ids.has(key) ? key : undefined;
|
|
33
|
+
}
|
|
34
|
+
function npmVersion(range) {
|
|
35
|
+
try {
|
|
36
|
+
return semver.minVersion(range)?.version;
|
|
37
|
+
}
|
|
38
|
+
catch {
|
|
39
|
+
return undefined;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
function pythonVersion(range) {
|
|
43
|
+
if (!range)
|
|
44
|
+
return undefined;
|
|
45
|
+
const match = /(?:>=|==|~=)\s*([^,\s]+)/.exec(range);
|
|
46
|
+
return match ? (semver.coerce(match[1])?.version ?? undefined) : undefined;
|
|
47
|
+
}
|
|
48
|
+
function parseRequirement(spec) {
|
|
49
|
+
const clean = spec.split(";")[0].trim();
|
|
50
|
+
const match = /^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:\[[^\]]*\])?\s*(.*)$/.exec(clean);
|
|
51
|
+
if (!match)
|
|
52
|
+
return { name: normalizePypi(clean) };
|
|
53
|
+
return { name: normalizePypi(match[1]), version: pythonVersion(match[2]) };
|
|
54
|
+
}
|
|
55
|
+
function table(value) {
|
|
56
|
+
return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
|
|
57
|
+
}
|
|
58
|
+
function tableVersion(value) {
|
|
59
|
+
if (typeof value === "string")
|
|
60
|
+
return value;
|
|
61
|
+
const version = table(value)?.version;
|
|
62
|
+
return typeof version === "string" ? version : undefined;
|
|
63
|
+
}
|
|
64
|
+
function strings(value) {
|
|
65
|
+
return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
|
|
66
|
+
}
|
|
67
|
+
/** Minimum version of a declaration, for either ecosystem. */
|
|
68
|
+
export function inRange(version, since, until) {
|
|
69
|
+
const current = version ? semver.coerce(version) : null;
|
|
70
|
+
if (!current)
|
|
71
|
+
return true;
|
|
72
|
+
const from = since ? semver.coerce(since) : null;
|
|
73
|
+
if (from && semver.lt(current, from))
|
|
74
|
+
return false;
|
|
75
|
+
const to = until ? semver.coerce(until) : null;
|
|
76
|
+
if (to && semver.gte(current, to))
|
|
77
|
+
return false;
|
|
78
|
+
return true;
|
|
79
|
+
}
|
|
80
|
+
export function detectStack(vault, dir) {
|
|
81
|
+
const index = techIndex(vault);
|
|
82
|
+
const techs = new Map();
|
|
83
|
+
const unknown = [];
|
|
84
|
+
const files = [];
|
|
85
|
+
const seenUnknown = new Set();
|
|
86
|
+
const addTech = (id, detectedVersion, source) => {
|
|
87
|
+
const version = index.databases.has(id) ? undefined : detectedVersion;
|
|
88
|
+
const found = techs.get(id);
|
|
89
|
+
if (!found)
|
|
90
|
+
techs.set(id, { id, version, source });
|
|
91
|
+
else if (!found.version && version)
|
|
92
|
+
found.version = version;
|
|
93
|
+
};
|
|
94
|
+
const addUnknown = (ecosystem, name, version) => {
|
|
95
|
+
const key = `${ecosystem}:${name}`;
|
|
96
|
+
if (seenUnknown.has(key))
|
|
97
|
+
return;
|
|
98
|
+
seenUnknown.add(key);
|
|
99
|
+
unknown.push({ ecosystem, name, version });
|
|
100
|
+
};
|
|
101
|
+
const addNpm = (name, range, source) => {
|
|
102
|
+
if (name.startsWith("@types/"))
|
|
103
|
+
return;
|
|
104
|
+
const version = npmVersion(range);
|
|
105
|
+
const id = lookup("npm", name, index);
|
|
106
|
+
if (id)
|
|
107
|
+
addTech(id, version, source);
|
|
108
|
+
else
|
|
109
|
+
addUnknown("npm", name, version);
|
|
110
|
+
};
|
|
111
|
+
const addPypi = (name, version, source) => {
|
|
112
|
+
if (!name)
|
|
113
|
+
return;
|
|
114
|
+
const id = lookup("pypi", name, index);
|
|
115
|
+
if (id)
|
|
116
|
+
addTech(id, version, source);
|
|
117
|
+
else
|
|
118
|
+
addUnknown("pypi", name, version);
|
|
119
|
+
};
|
|
120
|
+
const npmFile = path.join(dir, NPM_FILE);
|
|
121
|
+
if (fs.existsSync(npmFile)) {
|
|
122
|
+
files.push(NPM_FILE);
|
|
123
|
+
try {
|
|
124
|
+
const raw = JSON.parse(fs.readFileSync(npmFile, "utf8"));
|
|
125
|
+
const deps = { ...raw.dependencies, ...raw.devDependencies };
|
|
126
|
+
for (const [name, range] of Object.entries(deps)) {
|
|
127
|
+
if (typeof range === "string")
|
|
128
|
+
addNpm(name, range, NPM_FILE);
|
|
129
|
+
}
|
|
130
|
+
if (typeof deps.typescript === "string")
|
|
131
|
+
addTech("typescript", npmVersion(deps.typescript), NPM_FILE);
|
|
132
|
+
}
|
|
133
|
+
catch {
|
|
134
|
+
// An unreadable manifest is reported by the tooling, not by detection.
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
const pyprojectFile = path.join(dir, PYPROJECT_FILE);
|
|
138
|
+
let requiresPython;
|
|
139
|
+
if (fs.existsSync(pyprojectFile)) {
|
|
140
|
+
files.push(PYPROJECT_FILE);
|
|
141
|
+
try {
|
|
142
|
+
const doc = parseToml(fs.readFileSync(pyprojectFile, "utf8"));
|
|
143
|
+
const project = table(doc.project);
|
|
144
|
+
for (const spec of strings(project?.dependencies)) {
|
|
145
|
+
const req = parseRequirement(spec);
|
|
146
|
+
addPypi(req.name, req.version, PYPROJECT_FILE);
|
|
147
|
+
}
|
|
148
|
+
const optional = table(project?.["optional-dependencies"]);
|
|
149
|
+
for (const value of Object.values(optional ?? {})) {
|
|
150
|
+
for (const spec of strings(value)) {
|
|
151
|
+
const req = parseRequirement(spec);
|
|
152
|
+
addPypi(req.name, req.version, PYPROJECT_FILE);
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
requiresPython = typeof project?.["requires-python"] === "string" ? project["requires-python"] : undefined;
|
|
156
|
+
const poetry = table(table(doc.tool)?.poetry);
|
|
157
|
+
const poetryDeps = table(poetry?.dependencies);
|
|
158
|
+
for (const [name, value] of Object.entries(poetryDeps ?? {})) {
|
|
159
|
+
if (name === "python")
|
|
160
|
+
continue;
|
|
161
|
+
addPypi(normalizePypi(name), pythonVersion(tableVersion(value)), PYPROJECT_FILE);
|
|
162
|
+
}
|
|
163
|
+
const groups = table(poetry?.group);
|
|
164
|
+
for (const group of Object.values(groups ?? {})) {
|
|
165
|
+
const deps = table(table(group)?.dependencies);
|
|
166
|
+
for (const [name, value] of Object.entries(deps ?? {})) {
|
|
167
|
+
addPypi(normalizePypi(name), pythonVersion(tableVersion(value)), PYPROJECT_FILE);
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
catch {
|
|
172
|
+
// Invalid TOML is left to the project's own tooling.
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
for (const file of [REQUIREMENTS_FILE, REQUIREMENTS_DEV_FILE]) {
|
|
176
|
+
const requirementsFile = path.join(dir, file);
|
|
177
|
+
if (!fs.existsSync(requirementsFile))
|
|
178
|
+
continue;
|
|
179
|
+
files.push(file);
|
|
180
|
+
for (const line of fs.readFileSync(requirementsFile, "utf8").split(/\r?\n/)) {
|
|
181
|
+
const clean = line.split("#")[0].trim();
|
|
182
|
+
if (!clean || clean.startsWith("-"))
|
|
183
|
+
continue;
|
|
184
|
+
const req = parseRequirement(clean);
|
|
185
|
+
addPypi(req.name, req.version, file);
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
const pythonSource = files.includes(PYPROJECT_FILE)
|
|
189
|
+
? PYPROJECT_FILE
|
|
190
|
+
: files.includes(REQUIREMENTS_FILE)
|
|
191
|
+
? REQUIREMENTS_FILE
|
|
192
|
+
: files.includes(REQUIREMENTS_DEV_FILE)
|
|
193
|
+
? REQUIREMENTS_DEV_FILE
|
|
194
|
+
: undefined;
|
|
195
|
+
if (pythonSource)
|
|
196
|
+
addTech("python", pythonVersion(requiresPython), pythonSource);
|
|
197
|
+
return { techs: [...techs.values()], unknown, files };
|
|
198
|
+
}
|
|
199
|
+
//# sourceMappingURL=detect.js.map
|